Skip to content

Razee4315/NetLogo-MCP

BranchesTags

Repository files navigation

NetLogo MCP

CI Python 3.10+ Ruff mypy MIT License

The first MCP (Model Context Protocol) server for NetLogo — enabling AI assistants to create, run, and analyze agent-based models through natural conversation.

Works with: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Copilot), Cline, Continue, Roo Code, Zed, OpenCode, Codex — any tool that supports MCP.

Why NetLogo MCP?

As an AI student taking an Agent-Based Modeling course, I searched for an MCP server to control NetLogo — nothing existed. So I built one.

Instead of manually writing NetLogo code, clicking buttons, and tweaking sliders, you tell your AI assistant what you want in plain English:

"Create a predator-prey model with 100 sheep and 20 wolves. Run it for 500 ticks and show me the population dynamics."

The AI writes the code, runs the simulation, and shows you the results — all through conversation.

How It Works

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

By default, a real NetLogo window opens so you can watch your simulations run live. Headless mode is available for CI or servers.

Features

  • Create models from code (AI wraps them in .nlogox format)
  • Run simulations, collect tick-by-tick data as markdown tables
  • Run BehaviorSpace experiments — list saved experiments, preview the run plan, drive parallel parameter sweeps via the headless launcher
  • Export view as PNG — visible inline in chat
  • Set global variables, sliders, switches
  • Get world state, agent counts, world dimensions, patch grids
  • Built-in NetLogo primitives, programming guide, and NetLogo 6→7 transition guide as MCP resources
  • Prompt templates for model analysis, ABM creation, parameter sweeps, BehaviorSpace experiments, and CoMSES exploration
  • Live GUI mode for teaching and real-time exploration
  • Token-efficient output modes (summary_only, max_rows decimation) for long runs

Tools

Tool Description
create_model(code) Create a new model from NetLogo code
open_model(path) Load an existing .nlogo/.nlogox model
command(netlogo_command) Execute a NetLogo command (setup, go, etc.)
report(reporter) Evaluate a reporter expression
run_simulation(ticks, reporters) Run N ticks, collect data as a table
set_parameter(name, value) Set a global variable / slider / switch
get_world_state() Get tick count, agent counts, world dimensions
get_agent_sample(breed, n, attributes) Sample N agents as a markdown table — fills the gap between counts and hand-crafted reporters
get_patch_data(attribute, max_cells) Get patch data as a 2D grid (for heatmaps); auto-downsamples above max_cells (default 10000)
export_view() Export current view as PNG image
save_model(name, code) Save model to file
export_world() Export full world state to CSV
close_model() Unload the current model and clear-all the workspace
server_info() Inspect server config (paths, GUI mode, headless launcher)
list_models() List model files in models directory
search_comses(query) Search the CoMSES Net model library
get_comses_model(uuid) Fetch metadata + citation text for one COMSES model
download_comses_model(uuid) Safely download + extract a COMSES archive
open_comses_model(uuid) Download (or reuse cache) and load NetLogo models
read_comses_files(uuid) Read ODD / source contents from a downloaded model
list_experiments() List BehaviorSpace experiments saved in the loaded model
preview_experiment(...) Preview a BehaviorSpace run plan (total runs, time estimate) without executing
run_experiment(...) Run a BehaviorSpace experiment headlessly (named or inline spec)

Plus 4 resources (primitives reference, programming guide, model source, NetLogo 6→7 transition guide) and 5 prompts (analyze_model, create_abm, parameter_sweep, explore_comses, behaviorspace_experiment).

BehaviorSpace integration

Run NetLogo's BehaviorSpace experiments from any MCP client. Three tools cover the workflow:

  1. list_experiments() — read the <experiments> section of the loaded .nlogox to inventory saved experiments. No JVM round-trip; instant.
  2. preview_experiment(...) — show the run plan (total runs, parameter combos, time estimate) without executing. Always run this before a long sweep.
  3. run_experiment(...) — drive NetLogo_Console --headless (or netlogo-headless.bat) in a separate JVM. Returns parsed results plus the path to the full table CSV.

Long runs are bounded by max_total_runs (default 200) and timeout_seconds (default 600); partial table CSV is preserved on timeout.

Try it with the behaviorspace_experiment prompt or just ask: "Run a BehaviorSpace experiment varying initial-density from 50 to 90 in steps of 10, three reps each, measuring count turtles."

CoMSES Net integration

NetLogo MCP can search and safely fetch any model from the CoMSES Net computational model library — the largest peer-reviewed ABM repository. NetLogo models load automatically; Python / R / Julia models are identified and cached locally so you can inspect their source and ODD documentation from any MCP client, including clients with no filesystem tools.

Try it with the explore_comses prompt or just ask: "Find me a predator-prey ABM on COMSES and run a short baseline."

Safety properties (applied to every download):

  • Archives streamed with a hard byte cap (COMSES_MAX_DOWNLOAD_MB, default 50 MB) enforced mid-stream, not just via HEAD.
  • Every zip member is path-traversal-validated before extraction.
  • Zip-bomb refusal on uncompressed-size overflow.
  • Extraction is atomic: downloads land in a temp dir first, then move to the cache only on success.
  • Cache directories are trusted only when they carry the .comses_complete marker.
  • "latest" is resolved to a concrete version before any cache path is computed; the resolved version is returned to the AI so follow-up reads stay pinned to the same slot.

Security Model

NetLogo MCP gives the connecting AI client arbitrary file and process I/O on the host machine, scoped to the user the server runs as. The command and create_model tools accept any NetLogo statement; NetLogo's standard primitives include file-open / file-write-line / file-delete, export-world / import-world, set-current-directory, and — via extensions — shell calls (sh), Python execution (py), and network I/O (web). Treat the trust boundary the same way you treat a local terminal: only connect this server to AI clients you trust as much as a shell.

Concretely:

  • The stdio transport assumes the parent client is trusted. There is no auth, and adding it wouldn't help — the parent process owns the file descriptors.
  • The models/ and exports/ directories are writable by any tool call. Don't point NETLOGO_MODELS_DIR at a location you wouldn't chmod o+w.
  • Models downloaded via open_comses_model are extracted with path-traversal and zip-bomb guards (see CoMSES Net integration above), but once loaded, any command call against them runs untrusted NetLogo code. Read the ODD doc and skim the source before running setups on third-party models.
  • Future versions may ship an opt-in NETLOGO_MCP_RESTRICTED=true mode that blocks dangerous primitives. The default will remain unrestricted — the product is "let the AI drive NetLogo," and a restricted default would break the core flow.

Prerequisites

Requirement Install via terminal? How
Python 3.10+ Yes Windows: winget install Python.Python.3.12 · macOS: brew install python@3.12 · Linux: sudo apt install python3.12
Java JDK 11+ Yes Windows: winget install EclipseAdoptium.Temurin.21.JDK · macOS: brew install --cask temurin · Linux: sudo apt install openjdk-21-jdk
Git Yes Windows: winget install Git.Git · macOS/Linux: usually pre-installed
NetLogo 7.0+ No — manual Download from ccl.northwestern.edu/netlogo

Only NetLogo requires manual download. Everything else can be installed via terminal, and the Zero-Config Setup prompt below handles those automatically.

Zero-Config Setup (Recommended)

If you're using an AI coding tool, copy the prompt below into your chat. The AI will detect your OS, find your NetLogo and Java installations, clone the repo, install dependencies, configure your MCP client, and tell you how to use it.

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.

Manual Installation

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

Configuration

Create a .env file in the project root (or set env vars in your MCP client config):

# 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

Environment Variables

Variable Required Description
NETLOGO_HOME Yes Path to your NetLogo installation directory
JAVA_HOME No Path to your JDK directory (auto-detected if not set)
NETLOGO_MODELS_DIR No Directory for model files (defaults to the current working directory's ./models)
NETLOGO_GUI No "true" (default) for live GUI window, "false" for headless
NETLOGO_EXPORTS_DIR No Directory for exported views/worlds (defaults to the current working directory's ./exports)
COMSES_MAX_DOWNLOAD_MB No Max CoMSES archive size in MB (default 50). Enforced mid-stream.
NETLOGO_EXPORTS_MAX_FILES No Max files retained in each exports/ subdirectory (default 200). Oldest are pruned after each export_view / export_world. Set to 0 to disable.
NETLOGO_MCP_RESTRICTED No Set to "true" to block dangerous NetLogo primitives (file-*, import-world, set-current-directory, extension shell escapes). Off by default — see Security Model.

Client Setup

The 3 most common clients are below. For Windsurf, Cline, Continue, Roo Code, Zed, OpenCode, Codex, and Claude Desktop — see docs/CLIENTS.md.

Claude Code

Add to your project's .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"
      }
    }
  }
}

Restart Claude Code and verify with /mcp.

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "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)

Add to .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 Code uses "servers" instead of "mcpServers".

GUI vs Headless Mode

Mode NETLOGO_GUI What Happens
Live GUI (default) "true" or omitted Opens a NetLogo window. Watch simulations run in real-time.
Headless "false" No window. Faster startup. See snapshots via export_view in chat.

The mode is set at startup — to switch, change the env var and restart your client.

Quick Start

Once connected, try these prompts in any MCP client:

> 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.

First tool call takes 30-60 seconds while the JVM starts. Don't click stop — the NetLogo window will appear when it's ready. After that, every call is instant.

Troubleshooting

Problem Solution
NETLOGO_HOME is not set Set the environment variable to your NetLogo install directory
JAVA_HOME is not set Set it to your JDK directory (not JRE)
JVM crashes on startup Make sure JAVA_HOME points to JDK 11+, not an older version
No model is loaded Call open_model or create_model before using other tools
First call hangs for 30-60s Normal — JVM is warming up. Don't click stop.
Server won't connect Run netlogo-mcp manually in terminal to see error output

Documentation

Listed on

MCP Badge

Author

Saqlain Abbas Email: saqlainrazee@gmail.com GitHub: @Razee4315 LinkedIn: @saqlainrazee

License

This project is licensed under the MIT License — free to use, modify, and distribute for any purpose.

About

The first MCP (Model Context Protocol) server for NetLogo, enabling AI assistants like Claude to create, run, and analyze agent-based models through natural conversation.

Topics

mcp netlogo mcp-server netlogo-models

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

17 stars

Watchers

0 watching

Forks

1 fork
Report repository

Contributors

Languages