NetLogo MCP: Control NetLogo with AI (MCP Server)

Ask in plain English. The AI writes the NetLogo code, runs it, and shows you what happened.

Everything NetLogo MCP can do

25 tools that let your AI assistant drive NetLogo from start to finish, from writing the model to sweeping its parameters.

Create models from chat

Describe a model and get working NetLogo code, with real interface widgets like sliders, switches, buttons, and monitors.

Run simulations

Step models forward and get tick by tick data back as clean tables, ready for analysis or plotting.

BehaviorSpace sweeps

Run parallel parameter experiments through NetLogo's headless launcher and get summarized results for every combination.

See the world

Export the NetLogo view as a PNG that shows up right in your chat, and inspect world state, agents, and patch grids.

CoMSES library

Search and safely run peer reviewed models from CoMSES Net, the largest curated library of agent-based models.

Watch it live

A real NetLogo window opens so you can watch your simulations run. Prefer a server? Switch to headless mode.

Set up NetLogo MCP

The only thing you install by hand is NetLogo. Let your AI do the rest.

Recommended · the easy way

Let your AI assistant install it for you

First install NetLogo 7+ yourself, that is the only manual step. Then paste the prompt below into your AI coding tool (Claude, Cursor, VS Code, and the rest). It detects your system, installs the server with pip, wires up your client's MCP config, and hands you a test prompt to try. No JSON editing on your part.

Need NetLogo? Download it here first.

the setup promptpaste into your AI tool

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, 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 set to my NetLogo path, and env.JAVA_HOME set to my JDK path.
- Use the exact JSON schema for my specific client (for example "type": "stdio" for Cursor, the "servers" key for VS Code).
- Preserve any existing config entries: merge, don't overwrite.
- Configure it for THIS project only (project-scope config), not globally, unless I say otherwise.

5. Tell me what to do next
- Tell me to fully restart my AI tool so the new MCP server loads.
- Tell me the NetLogo window opens on the FIRST model tool call, and that call takes 30 to 60 seconds while the Java Virtual Machine starts. Tell me NOT to click stop during this wait.
- Give me this 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 (the 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.

Or configure it manually

Install

Run pip install netlogo-mcp. You will need NetLogo 7 and a Java JDK, or grab the Docker image that bundles both.

Connect

Add one netlogo entry to your client's config. Pick your tool below and copy the snippet.

Just ask

Tell your assistant what to model. It writes the code, runs the simulation, and shows you the results.

.mcp.json

{
  "mcpServers": {
    "netlogo": {
      "command": "netlogo-mcp",
      "env": {
        "NETLOGO_HOME": "C:/Program Files/NetLogo 7.0.3",
        "JAVA_HOME": "C:/Program Files/Eclipse Adoptium/jdk-21"
      }
    }
  }
}

claude_desktop_config.json

{
  "mcpServers": {
    "netlogo": {
      "command": "netlogo-mcp",
      "env": {
        "NETLOGO_HOME": "C:/Program Files/NetLogo 7.0.3",
        "JAVA_HOME": "C:/Program Files/Eclipse Adoptium/jdk-21"
      }
    }
  }
}

.cursor/mcp.json

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

.vscode/mcp.json

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

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "netlogo": {
      "command": "netlogo-mcp",
      "env": {
        "NETLOGO_HOME": "C:/Program Files/NetLogo 7.0.3",
        "JAVA_HOME": "C:/Program Files/Eclipse Adoptium/jdk-21"
      }
    }
  }
}

Using Cline, Continue, Roo Code, Zed, OpenCode, or Codex? The exact config for all 11 clients lives in docs/CLIENTS.md.

Works with your AI assistant

Any tool that speaks the Model Context Protocol.

Claude Code Claude Desktop Cursor Windsurf VS Code · Copilot Cline Continue Roo Code Zed OpenCode Codex

Frequently asked questions

What is NetLogo MCP?

NetLogo MCP is the first Model Context Protocol (MCP) server for NetLogo. It connects AI assistants like Claude, Cursor, and VS Code Copilot to NetLogo, so you can create, run, and analyze agent-based models by typing what you want in plain English.

Which AI assistants work with it?

Any client that speaks MCP: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Copilot), Cline, Continue, Roo Code, Zed, OpenCode, and Codex.

Do I need NetLogo installed?

Yes. NetLogo MCP drives a real NetLogo install (7.0 or newer) through its Java runtime, so you need NetLogo and a Java JDK 11 or newer. If you would rather not install anything on the host, use the Docker image, which bundles headless NetLogo and its Java runtime.

Is it free?

Yes. NetLogo MCP is free and open source under the MIT license. No account and no ads. The code lives on GitHub.

Start modeling by conversation

Install in one command, connect your AI client, and let it run the simulation for you.

Install from PyPI Star on GitHub

Free and open source · MIT · Windows, macOS and Linux