Net Logo MCP

NetLogo的第一个MCP（模型上下文协议）服务器——使AI助手能够通过自然对话创建、运行和分析基于代理的模型。

适用于： Claude Code、Claude Desktop、Cursor、Windsurf、VS Code（Copilot）、Cline、Continue、Roo Code、Zed、OpenCode、Codex——任何支持MCP的工具。

为什么选择NetLogo MCP？

作为一名正在学习基于代理的建模课程的人工智能学生，我搜索了一个MCP服务器来控制NetLogo——什么都没有。所以我建了一个。

你不用手动编写NetLogo代码、点击按钮和调整滑块，而是用简单的英语告诉你的AI助手你想要什么：

“用100只绵羊和20只狼创建一个捕食者-猎物模型。运行500只蜱虫，向我展示种群动态。”

人工智能编写代码，运行模拟，并通过对话向您显示结果。

运作原理

You (in any MCP client) → AI Assistant → MCP Protocol → NetLogo MCP Server → NetLogo (GUI or headless JVM)

默认情况下，会打开一个真实的NetLogo窗口，以便您可以实时观看模拟运行。无头模式可用于CI或服务器。

特性

• 从代码创建模型（AI将其封装在其中 .nlogox 格式）
• 运行模拟，收集逐点数据作为标记表
• 运行BehaviorSpace实验 --列出保存的实验，预览运行计划，通过无头启动器驱动并行参数扫描
• 将视图导出为PNG格式——在聊天中可见
• 设置全局变量、滑块、开关
• 获取世界状态、代理计数、世界维度、补丁网格
• 内置NetLogo原语、编程指南和 NetLogo 6→7 过渡指南 作为MCP资源
• 用于模型分析、ABM创建、参数扫描、BehaviorSpace实验和CoMSES探索的提示模板
• 用于教学和实时探索的实时GUI模式
• 令牌高效输出模式(summary_only, max_rows 抽选）用于长期运行

工具

加上4个资源（原语参考、编程指南、模型源、， NetLogo 6→7 过渡指南)5个提示(analyze_model, create_abm, parameter_sweep, explore_comses, behaviorspace_experiment).

行为空间整合

从任何MCP客户端运行NetLogo的BehaviorSpace实验。三个工具涵盖了工作流程：

1. list_experiments() --阅读 ` 装载部分 .nlogox` 对节省的实验进行盘点。没有JVM往返；瞬间。
2. preview_experiment(...) --在不执行的情况下显示运行计划（总运行次数、参数组合、时间估计）。在大扫除之前，一定要先跑这个。
3. run_experiment(...) --驱动器 NetLogo_Console --headless （或 netlogo-headless.bat)在单独的JVM中。返回解析结果以及CSV全表的路径。

长跑受到以下因素的限制 max_total_runs （默认值200）和 timeout_seconds （默认值为600）；部分表CSV在超时时保留。

试试这个 behaviorspace_experiment 提示或只是问： *“进行一项BehaviorSpace实验，以10步为一步，将初始密度从50到90不等，每次三次，测量海龟数量。”*

CoMSES-Net集成

NetLogo MCP可以搜索并安全地从 CoMSES-Net计算模型库 --最大的同行评审ABM存储库。NetLogo模型自动加载；Python/R/Julia模型在本地被识别和缓存，因此您可以从任何MCP客户端（包括没有文件系统工具的客户端）检查它们的源代码和ODD文档。

试试这个 explore_comses 提示或只是问： *“在COMSES上给我找一个捕食者-猎物ABM，并运行一个简短的基线。”*

安全属性（适用于每次下载）：

• 档案以硬字节上限流式传输(COMSES_MAX_DOWNLOAD_MB，默认50MB）强制中流，而不仅仅是通过HEAD。
• 在提取之前，每个zip成员都经过路径遍历验证。
• 未压缩尺寸溢出时拉链炸弹被拒绝。
• 提取是原子性的：首先下载到临时目录中，然后只有在成功后才能移动到缓存中。
• 缓存目录只有在携带 .comses_complete 标记。
• "latest" 在计算任何缓存路径之前，解析为具体版本；解析后的版本被返回给AI，因此后续读取保持固定在同一插槽中。

安全模型

NetLogo MCP提供连接AI客户端 主机上的任意文件和进程I/O，仅限于服务器运行的用户 command 和 create_model 工具接受任何NetLogo声明；NetLogo的标准原语包括 file-open / file-write-line / file-delete, export-world / import-world, set-current-directory，并通过扩展名调用shell(sh)，Python执行(py)，以及网络I/O(web).像对待本地终端一样对待信任边界： 只将此服务器连接到您信任的AI客户端，就像shell一样。

具体来说：

• stdio传输假定父客户端是受信任的。没有身份验证，添加它也无济于事——父进程拥有文件描述符。
• 这 models/ 和 exports/ 任何工具调用都可以写入目录。不要指着 NETLOGO_MODELS_DIR 在一个你不会去的地方 chmod o+w.
• 模型下载通过 open_comses_model 使用路径遍历和zip炸弹防护进行提取（请参阅上面的CoMSES-Net集成），但 加载后，任何 command 对它们的调用运行不受信任的NetLogo代码.在第三方模型上运行安装程序之前，请阅读ODD文档并浏览源代码。
• 未来的版本可能会提供选择加入功能 NETLOGO_MCP_RESTRICTED=true 阻止危险图元的模式。默认设置将保持不受限制——该产品是“让AI驱动NetLogo”，而受限制的默认设置将破坏核心流程。

先决条件

只有NetLogo需要手动下载。 其他所有内容都可以通过终端安装，下面的Zero Config Setup提示符会自动处理这些内容。

零配置设置（推荐）

如果您正在使用AI编码工具，请将下面的提示复制到您的聊天中。AI将检测您的操作系统，查找您的NetLogo和Java安装，克隆仓库，安装依赖关系，配置MCP客户端，并告诉您如何使用它。

Click to copy the setup prompt

Please set up the NetLogo MCP server for me end-to-end. Follow these steps carefully:

1. **Detect my environment**
   - Identify my OS (Windows / macOS / Linux).
   - Check Python version (need 3.10+). If missing, tell me to install it first and stop.
   - Check for Java JDK 11+ (not JRE). Look in common locations (JAVA_HOME env var, standard install dirs). If missing, tell me to install Adoptium Temurin JDK 11+ and stop.
   - Check for NetLogo 7.0+. Look in common locations:
     - Windows: `C:/Program Files/NetLogo*`
     - macOS: `/Applications/NetLogo*`
     - Linux: `/opt/netlogo*`, `~/netlogo*`
     If NetLogo isn't installed, tell me to download it from https://ccl.northwestern.edu/netlogo/download.shtml and stop.

2. **Clone and install**
   - Pick a sensible parent directory (e.g. my home folder or `~/projects`).
   - Run: `git clone https://github.com/Razee4315/NetLogo-MCP.git`
   - `cd` into the cloned directory.
   - Run: `pip install -e .`
   - Verify the `netlogo-mcp` command is now available on my PATH.

3. **Identify my MCP client**
   - Figure out which AI tool I'm using (Claude Code, Cursor, Windsurf, Cline, Continue, Roo Code, Zed, OpenCode, VS Code Copilot, Codex, or Claude Desktop).
   - If you're not sure, ask me.

4. **Configure the MCP client**
   - Locate (or create) the correct config file for my client (see docs/CLIENTS.md for exact paths and schemas).
   - Add a `netlogo` server entry with:
     - `command`: `netlogo-mcp`
     - `env.NETLOGO_HOME`: the NetLogo path you detected
     - `env.JAVA_HOME`: the JDK path you detected
     - `env.NETLOGO_GUI`: `"true"` (default — opens a live NetLogo window)
   - Use the exact JSON schema for my specific client (e.g. `"type": "stdio"` for Cursor, `"servers"` key for VS Code).
   - Preserve any existing config entries — merge, don't overwrite.

5. **Tell me what to do next**
   - Tell me to fully restart my AI tool for the new MCP server to load.
   - Warn me that the FIRST tool call takes 30–60 seconds while the Java Virtual Machine starts (the NetLogo GUI window will appear when it's ready). Tell me NOT to click stop during this wait.
   - Give me this exact test prompt to try after restart:

     > "Create a simple predator-prey model with wolves and sheep on a green landscape. Run setup, then run 100 ticks while tracking wolf and sheep counts. Export the view before and after so I can see how the world evolved."

   - Tell me where models and exports are saved (by default, the current working directory's `models/` and `exports/` folders) and that I can browse them with the `list_models` tool.

Do not skip any verification step. If something fails, stop and tell me exactly what failed and how to fix it.

手动安装

git clone https://github.com/Razee4315/NetLogo-MCP.git
cd NetLogo-MCP
pip install -e .

配置

创建一个 .env 项目根目录中的文件（或在MCP客户端配置中设置env变量）：

# Windows
NETLOGO_HOME=C:/Program Files/NetLogo 7.0.3
JAVA_HOME=C:/Program Files/Eclipse Adoptium/jdk-25.0.2.10-hotspot

# macOS
# NETLOGO_HOME=/Applications/NetLogo 7.0.3
# JAVA_HOME=/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home

# Linux
# NETLOGO_HOME=/opt/netlogo-7.0.3
# JAVA_HOME=/usr/lib/jvm/java-21-openjdk

环境变量

客户端设置

下面是三个最常见的客户。 关于Windsurf、Cline、Continue、Roo Code、Zed、OpenCode、Codex和Claude Desktop，请参阅 docs/CLIENTS.md.

Claude Code

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "netlogo": {
      "command": "netlogo-mcp",
      "args": [],
      "env": {
        "NETLOGO_HOME": "C:/Program Files/NetLogo 7.0.3",
        "JAVA_HOME": "C:/Program Files/Eclipse Adoptium/jdk-25.0.2.10-hotspot"
      }
    }
  }
}

重新启动Claude Code并用验证 /mcp.

Cursor

添加 .cursor/mcp.json （项目）或 ~/.cursor/mcp.json （全球）：

{
  "mcpServers": {
    "netlogo": {
      "type": "stdio",
      "command": "netlogo-mcp",
      "args": [],
      "env": {
        "NETLOGO_HOME": "C:/Program Files/NetLogo 7.0.3",
        "JAVA_HOME": "C:/Program Files/Eclipse Adoptium/jdk-25.0.2.10-hotspot"
      }
    }
  }
}

VS Code (Copilot)

添加 .vscode/mcp.json:

{
  "servers": {
    "netlogo": {
      "type": "stdio",
      "command": "netlogo-mcp",
      "args": [],
      "env": {
        "NETLOGO_HOME": "C:/Program Files/NetLogo 7.0.3",
        "JAVA_HOME": "C:/Program Files/Eclipse Adoptium/jdk-25.0.2.10-hotspot"
      }
    }
  }
}

VS代码使用 "servers" 而不是 "mcpServers".

GUI与无头模式

模式在启动时设置——切换、更改env变量并重新启动客户端。

快速开始

连接后，在任何MCP客户端中尝试以下提示：

> Create a simple NetLogo model with 50 turtles doing a random walk.
  Run setup, simulate 100 ticks, and export the view.

> Open the Wolf Sheep Predation model and run a parameter sweep
  on initial-number-wolves from 10 to 100.

> Build a disease spread model with susceptible, infected, and
  recovered agents on a grid.

第一次工具调用需要30-60秒 JVM启动时。不要单击停止——NetLogo窗口将在准备就绪时出现。在那之后，每个电话都是即时的。

故障排除

文档

• docs/CLIENTS.md --为所有11个MCP客户端设置
• docs/DEVELOPMENT.md --项目结构、运行测试、架构说明
• 贡献.md --如何做出贡献
• 更改日志.md --版本历史

上市于

](https://lobehub.com/mcp/razee4315-netlogo_mcp)

作者

保存阿巴斯 电子邮件：saqlainrazee@gmail.com github： @Razee4315 领英： @saveinrazee

许可证

该项目根据 MIT许可证 --可以出于任何目的自由使用、修改和分发。