NetLogo-MCP

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 — any tool that supports MCP.

Why NetLogo MCP?

As an AI student in my 6th semester, I was taking an Agent-Based Modeling course that heavily uses NetLogo. When I discovered MCP (Model Context Protocol) and how it lets AI assistants interact with external tools, I immediately searched for a NetLogo MCP server. Nothing existed — not for NetLogo, not for any agent-based modeling platform.

So I built one.

The idea is simple: instead of manually writing NetLogo code, clicking buttons, and tweaking sliders, you just 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." "What happens if we double the wolf reproduction rate?" The AI handles the code, runs the simulation, and shows you the results — all through conversation.

This bridges the gap between AI-powered assistance and agent-based modeling, making NetLogo accessible to anyone who can describe what they want to simulate.

How It Works

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

The server runs NetLogo in headless mode (no GUI) as a background Java process. Your AI sends commands through the MCP protocol, NetLogo executes them, and results come back — including simulation data, agent counts, and exported view snapshots you can see right in the chat.

Features

• Create Models from Code — Write NetLogo procedures, the AI wraps them in the proper format and loads them
• Run Simulations — Execute setup, go, or any custom command with full control
• Collect Data — Run N ticks and collect reporter data as markdown tables
• Visual Snapshots — Export the current world view as PNG images, visible inline in chat
• Parameter Control — Set globals, sliders, and switches programmatically
• World Inspection — Get tick counts, agent counts, world dimensions, and patch data grids
• Model Library — Browse and load .nlogo/.nlogox files from a models directory
• Built-in References — NetLogo primitives and programming guide as MCP resources
• Prompt Templates — Pre-built workflows for model analysis, ABM creation, and parameter sweeps
• Live GUI Mode — Optional: open a real NetLogo window to watch simulations run in real-time

Tools

Resources

Prompts

Prerequisites

• Python 3.10+
• Java JDK 11+ — Adoptium Temurin recommended
• NetLogo 7.0+ — Download

Installation

# Clone the repository
git clone https://github.com/Razee4315/NetLogo_MCP.git
cd NetLogo_MCP

# Install the package
pip install -e .

Configuration

Copy .env.example to .env and set your paths:

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

Environment Variables

Client Setup

This server uses the MCP stdio transport, which is supported by all major AI coding tools. Pick your tool below.

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",
        "NETLOGO_MODELS_DIR": "C:/path/to/NetLogo_MCP/models"
      }
    }
  }
}

Restart Claude Code and verify with /mcp.

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.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"
      }
    }
  }
}

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"
      }
    }
  }
}

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"
      }
    }
  }
}

Note: VS Code uses "servers" instead of "mcpServers".

Add to ~/.codeium/windsurf/mcp_config.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"
      }
    }
  }
}

Add via Cline settings UI, or edit cline_mcp_settings.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"
      },
      "disabled": false
    }
  }
}

Add to .roo/mcp.json (project) or via VS Code settings:

{
  "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"
      },
      "disabled": false
    }
  }
}

Create .continue/mcpServers/netlogo.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"
      }
    }
  }
}

Note: MCP tools only work in Continue's Agent mode.

Add to Zed settings.json:

{
  "context_servers": {
    "netlogo": {
      "command": {
        "path": "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"
        }
      }
    }
  }
}

Note: Zed uses "context_servers" with a nested "command" object.

Add to opencode.json (project root) or ~/.config/opencode/opencode.json:

{
  "mcp": {
    "netlogo": {
      "type": "local",
      "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"
      }
    }
  }
}

Note: OpenCode uses "mcp" as the root key and "type": "local" for stdio.

Headless vs GUI Mode

Note: GUI mode runs NetLogo on a separate thread so the MCP server stays responsive. 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.

Tech Stack

• Server: FastMCP (Python)
• NetLogo Bridge: pynetlogo + JPype
• Runtime: NetLogo headless JVM
• Transport: MCP stdio protocol

Project Structure

NetLogo_MCP/
├── pyproject.toml              # Package config, linting & type check settings
├── smithery.yaml               # Smithery registry configuration
├── .mcp.json                   # Claude Code MCP configuration
├── .pre-commit-config.yaml     # Pre-commit hooks (ruff, mypy)
├── .github/workflows/ci.yml    # CI pipeline (lint, type check, test)
├── CHANGELOG.md                # Version history
├── src/
│   └── netlogo_mcp/
│       ├── server.py           # FastMCP app, stdout protection, lifespan
│       ├── tools.py            # All 12 tools
│       ├── resources.py        # 3 resources (docs + model source)
│       ├── prompts.py          # 3 prompts (analyze, create, sweep)
│       ├── config.py           # Environment variable loading
│       ├── py.typed            # PEP 561 type marker
│       └── data/
│           ├── primitives.md   # NetLogo primitives reference
│           └── programming_guide.md
├── models/                     # Drop .nlogo/.nlogox files here
└── tests/
    ├── conftest.py             # Mock fixtures (no JVM needed)
    ├── test_tools.py
    └── test_resources.py

Running Tests

# Run tests
pytest tests/ -v

# Run tests with coverage
pytest tests/ -v --cov=netlogo_mcp --cov-report=term-missing

Tests use mock fixtures — no Java/NetLogo installation needed to run them.

Troubleshooting

Contributing

Contributions are welcome! This is an open project — feel free to open issues, suggest features, or submit pull requests. See CONTRIBUTING.md for details.

Listed on

Author

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

License

This project is source available with restricted commercial use:

• Personal use — Free to use, copy, and modify
• Commercial use — Requires written permission from the author

See the LICENSE file for full details.