NetLogo MCP

NetLogo 向けの最初の MCP（Model Context Protocol）サーバーです。AI アシスタントが自然な会話を通じてエージェントベースモデルを作成、実行、分析できるようにします。

対応ツール: Claude Code、Claude Desktop、Cursor、Windsurf、VS Code（Copilot）、Cline、Continue、Roo Code、Zed、OpenCode、Codex — MCP をサポートするあらゆるツール。

なぜ NetLogo MCP なのか？

エージェントベースモデリングの講義を受けている AI 専攻の学生として、NetLogo を操作する MCP サーバーを探しましたが、存在しませんでした。そこで自分で作りました。

NetLogo のコードを手作業で書き、ボタンをクリックし、スライダーを微調整する代わりに、AI アシスタントに平易な英語でこう伝えるだけです。

"100 匹の羊と 20 匹の狼がいる捕食者・被食者モデルを作成してください。500 ティック実行して、個体群動態を見せてください。"

AI がコードを書き、シミュレーションを実行し、結果を表示します — すべて会話を通じて行えます。

デフォルトでは（初回使用時に）実際の NetLogo ウィンドウが開き、シミュレーションがライブで実行される様子を確認できます。CI やサーバー向けにヘッドレスモードも利用できます。

機能

• コードからモデルを作成 — スライダー、スイッチ、ボタン、モニターといった実際のインターフェースウィジェット付き
• シミュレーションを実行 し、ティックごとのデータを Markdown テーブルとして収集
• BehaviorSpace 実験を実行 — ヘッドレスランチャーによる並列パラメータースイープ
• ビューを PNG としてエクスポート — チャット内にインラインで表示
• あらゆるものを検査 — ワールドの状態、エージェントのサンプル、ヒートマップ用のパッチグリッド
• CoMSES Net 連携 — 最大の査読済み ABM ライブラリからモデルを検索し、安全に実行
• 組み込みリファレンス — NetLogo のプリミティブ、プログラミングガイド、6→7 移行ガイドを MCP リソースとして提供
• 遅延起動 — NetLogo ウィンドウは実際にツールを使用したときにのみ開き、AI クライアントが接続したときには開きません

25 個すべてのツール、ウィジェットスキーマ、プロンプトの完全なリファレンスについては docs/TOOLS.md をご覧ください。

前提条件

手動ダウンロードが必要なのは NetLogo のみです。 それ以外はすべてターミナルからインストールでき、以下のゼロコンフィグセットアップ用プロンプトがそれらを自動的に処理します。

ゼロコンフィグセットアップ (推奨)

AI コーディングツールを使用している場合は、以下のプロンプトをチャットにコピーしてください。AI がお使いの OS を検出し、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 で確認します。

ヒント: グローバル設定よりもプロジェクトスコープの設定 (1 つのプロジェクト内の .mcp.json) を推奨します — グローバルエントリはすべてのプロジェクトのすべてのセッションでサーバーを読み込んでしまいます。

Cursor、Windsurf、VS Code、Cline、Continue、Roo Code、Zed、OpenCode、Codex、Claude Desktop をお使いですか? 11 個のクライアントすべての正確な設定については docs/CLIENTS.md を参照してください。すべての設定オプション (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.

最初のモデルツール呼び出しは JVM の起動中に 30〜60 秒かかります — 準備が整うと NetLogo ウィンドウが表示されます。停止をクリックしないでください。それ以降の呼び出しはすべて即時です。

トラブルシューティング

ドキュメント

• docs/TOOLS.md — ツールの完全なリファレンス、ウィジェットスキーマ、BehaviorSpace および CoMSES ガイド
• docs/CONFIGURATION.md — すべての環境変数、GUI とヘッドレス、起動タイミング
• docs/SECURITY.md — セキュリティモデルと信頼境界
• docs/CLIENTS.md — 11 個の MCP クライアントすべてのセットアップ
• docs/DEVELOPMENT.md — プロジェクト構成、テストの実行、アーキテクチャに関するメモ
• CONTRIBUTING.md — コントリビュート方法
• CHANGELOG.md — バージョン履歴

掲載先

引用

研究や教育で NetLogo MCP を使用する場合は、引用してください — GitHub サイドバーの 「Cite this repository」 をクリックするか、CITATION.cff を参照してください。

作者

Saqlain Abbas Email: [email protected] GitHub: @Razee4315 LinkedIn: @saqlainrazee

ライセンス

このプロジェクトは MIT License の下でライセンスされています — あらゆる目的で自由に使用、変更、配布できます。