mcpField
N
NetLogo MCP

NetLogo MCP

本地服务
github.com科研与教育2716 周前更新
代码仓库访问官网

关于 NetLogo MCP

NetLogo MCP 是首个面向 NetLogo 的 MCP 服务，允许 AI 助手通过自然语言创建、运行和分析基于主体的模型。适合学习和开展 ABM 研究的用户，并可访问 CoMSES Net 上经同行评审的模型库。

主要功能

  1. 01通过代码创建带界面控件的模型
  2. 02运行仿真并以 Markdown 表格输出逐 tick 数据
  3. 03通过 BehaviorSpace 进行并行参数扫描
  4. 04将视图导出为 PNG 图片
  5. 05访问 CoMSES Net 模型库
  6. 06提供 NetLogo 参考资料作为 MCP 资源

适用场景

  1. 01根据自然语言描述搭建捕食者-猎物等模型并运行
  2. 02对模型参数进行批量扫描并分析种群动态
  3. 03在课程或研究中检查并运行 CoMSES Net 上的已发布模型

MCP 相关

NetLogo MCP 作为 MCP 服务运行，向支持 MCP 的客户端提供 25 个工具以及 NetLogo 参考资料等资源。

#netlogo#agent-based-modeling#simulation#research#complexity-science#behaviorspace

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "NetLogo-MCP": {
      "command": "uvx",
      "args": [
        "netlogo-mcp"
      ],
      "env": {
        "NETLOGO_HOME": "<NETLOGO_HOME>",
        "JAVA_HOME": "<JAVA_HOME>",
        "NETLOGO_GUI": "<NETLOGO_GUI>"
      }
    }
  }
}
启动命令uvx netlogo-mcp
需要配置的环境变量
NETLOGO_HOMEPath to the NetLogo 7.0+ installation directory (e.g. C:/Program Files/NetLogo 7.0.3)
JAVA_HOMEPath to a Java JDK 11+ installation (not a JRE)
NETLOGO_GUISet to false for headless mode (no NetLogo window); default true

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
pypinetlogo-mcp1.0.2

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

NetLogo MCP — 与 NetLogo 对话。AI 运行仿真。

PyPI CI Python 3.10+ Ruff mypy MIT License

首个面向 NetLogo 的 MCP（Model Context Protocol）服务，让 AI 助手能够通过自然对话创建、运行和分析基于 Agent 的模型。

兼容： Claude Code、Claude Desktop、Cursor、Windsurf、VS Code（Copilot）、Cline、Continue、Roo Code、Zed、OpenCode、Codex——以及任何支持 MCP 的工具。

NetLogo MCP 演示 — AI 通过对话创建并运行仿真

为什么选择 NetLogo MCP？

作为一名学习基于 Agent 的建模课程的 AI 专业学生，我曾寻找能控制 NetLogo 的 MCP 服务——却一无所获。于是我自己动手构建了一个。

你不必再手动编写 NetLogo 代码、点击按钮和调整滑块，只需用通俗的语言告诉 AI 助手你的需求：

“创建一个包含 100 只羊和 20 只狼的捕食者—猎物模型。运行 500 个时间步，并展示种群动态。”

AI 会编写代码、运行仿真并展示结果——全程通过对话完成。

你 → AI 助手 → NetLogo MCP 服务 → NetLogo（GUI 或无头 JVM）

默认情况下，首次使用时会打开真实的 NetLogo 窗口，让你实时观察仿真运行。CI 或服务器环境可使用无头模式。

功能

  • 通过代码创建模型——并包含真实的界面控件：滑块、开关、按钮和监视器
  • 运行仿真并将逐时间步数据收集为 Markdown 表格
  • 运行 BehaviorSpace 实验——通过无头启动器并行扫描参数
  • 将视图导出为 PNG——可直接在聊天中查看
  • 检查所有内容——世界状态、Agent 样本，以及用于热力图的补丁网格
  • 集成 CoMSES Net——搜索并安全运行来自最大同行评审 ABM 模型库的模型
  • 内置参考资料——NetLogo 基元、编程指南，以及作为 MCP 资源提供的 6→7 迁移指南
  • 延迟启动——NetLogo 窗口只会在你实际使用工具时打开，而不会在 AI 客户端连接时打开

请参阅 docs/TOOLS.md，了解全部 25 个工具、控件架构和提示词的完整参考。

先决条件

要求可通过终端安装？方法
Python 3.10+是Windows：winget install Python.Python.3.12 · macOS：brew install [email protected] · Linux：sudo apt install python3.12
Java JDK 11+是Windows：winget install EclipseAdoptium.Temurin.21.JDK · macOS：brew install --cask temurin · Linux：sudo apt install openjdk-21-jdk
NetLogo 7.0+否——需手动安装从 ccl.northwestern.edu/netlogo 下载

只有 NetLogo 需要手动下载。 其他所有内容都可以通过终端安装，下方的零配置设置提示词会自动处理这些步骤。

零配置设置（推荐）

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

点击复制设置提示词 
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. **Install**
   - Run: `pip install netlogo-mcp`
   - 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
     https://github.com/Razee4315/NetLogo-MCP/blob/main/docs/CLIENTS.md
     for exact paths and schemas per client).
   - 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
   - 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.
   - IMPORTANT: configure it for THIS project only (project-scope config file), not globally, unless I say otherwise — a global entry loads the server in every session.

5. **Tell me what to do next**
   - Tell me to fully restart my AI tool for the new MCP server to load.
   - Tell me the NetLogo window opens on the FIRST model tool call, and that call takes 30–60 seconds while the Java Virtual Machine starts. 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.

手动安装

pip install netlogo-mcp

然后将服务添加到 MCP 客户端。对于 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 验证。

提示： 优先使用项目范围的配置（单个项目中的 .mcp.json），而不是全局配置——全局条目会在每个项目的每个会话中加载服务。

使用 Cursor、Windsurf、VS Code、Cline、Continue、Roo Code、Zed、OpenCode、Codex 或 Claude Desktop？ 请参阅 docs/CLIENTS.md，了解全部 11 个客户端的准确配置。所有配置选项（GUI／无头模式、目录、限制）请参阅 docs/CONFIGURATION.md。

正在开发或贡献？ 请克隆仓库并以可编辑模式安装：

git clone https://github.com/Razee4315/NetLogo-MCP.git
cd NetLogo-MCP
pip install -e ".[dev]"
Docker

此镜像内置了 NetLogo（无头模式）及其捆绑的 JRE——无需在主机上安装：

docker build -t netlogo-mcp .
docker run -i --rm netlogo-mcp

MCP 客户端配置：

{
  "mcpServers": {
    "netlogo": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "netlogo-mcp"]
    }
  }
}

Docker 仅以无头模式运行（不支持 GUI 模式）。添加 -v ./exports:/data/exports，将导出的视图和世界保存在主机上。

快速开始

连接后，在任意 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 sliders for population size and
  infection chance.

首次调用模型工具需要 30-60 秒，因为 JVM 正在启动——准备就绪后，NetLogo 窗口会出现。请勿点击停止。此后的每次调用都会立即完成。

故障排除

问题解决方案
NETLOGO_HOME is not set将环境变量设置为 NetLogo 的安装目录
JAVA_HOME is not set将其设置为 JDK 目录（而非 JRE）
JVM 启动时崩溃确保 JAVA_HOME 指向 JDK 11 或更高版本，而不是旧版本
No model is loaded使用其他工具前，先调用 open_model 或 create_model
首次模型调用挂起 30-60 秒这是正常现象——JVM 正在预热。请勿点击停止。
AI 客户端启动时 NetLogo 窗口打开你设置了 NETLOGO_EAGER_START=true，或正在使用旧版本——默认情况下，窗口仅在首次使用工具时打开
服务无法连接在终端中手动运行 netlogo-mcp，查看错误输出

文档

收录于

MCP Badge

引用

如果你在研究或教学中使用 NetLogo MCP，请引用它——点击 GitHub 侧边栏中的 “引用此仓库”，或参阅 CITATION.cff。

作者

Saqlain Abbas 电子邮件：[email protected] GitHub：@Razee4315 LinkedIn：@saqlainrazee

许可证

本项目采用 MIT License 授权——可出于任何目的免费使用、修改和分发。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。