SUMO-MCP: MCP Server for SUMO Traffic Simulation (LLM-Oriented)

中文文档

SUMO-MCP is a middleware layer connecting Large Language Models (LLMs) with Eclipse SUMO traffic simulation. Through Model Context Protocol (MCP), AI agents (such as Claude, Cursor, and TRAE) can directly call SUMO capabilities for end-to-end automation across OpenStreetMap data retrieval, network generation, demand modeling, simulation execution, and signal optimization.

The system supports both offline workflows (file-based pipelines) and online interaction (real-time TraCI control), covering use cases from macroscopic planning to microscopic control.

API reference: doc/API.md (the single source of truth remains tool registration in src/server.py). ezdesignX conversion guide: doc/EZDESIGNX_TO_SUMO.md.

Core Features

1. Unified Toolchain

Core MCP interfaces are grouped into intuitive tools to simplify common SUMO operations:

• Network Management (manage_network): Generate networks (generate), download OSM data (download_osm), convert formats (convert), and convert ezdesignX v1 JSON/JSONC (convert_ezdesignx). A dedicated convert_ezdesignx_network tool is also available.
• Demand Management (manage_demand): Generate random trips (generate_random), convert OD matrices (convert_od), and compute routes (compute_routes).
• Signal Optimization (optimize_traffic_signals): Includes cycle adaptation (cycle_adaptation) and coordination (coordination). cycle_adaptation outputs SUMO <additional> signal plans (automatically mounted into <additional-files> by workflows).
• Simulation & Analysis: Run standard config-based simulation (run_simple_simulation) and FCD trajectory analysis (run_analysis).

Some aggregated tools accept params.options: list[str], which are appended token-by-token to underlying SUMO binaries/scripts (see "General Conventions" in doc/API.md).

2. Online Interaction

Real-time control via TraCI enables fine-grained closed-loop operations:

• Simulation Control (control_simulation): Connect (connect), step (step), and cleanly disconnect (disconnect).
• State Query (query_simulation_state): Fetch active vehicle IDs (vehicle_list), per-vehicle variables (vehicle_variable), and global simulation statistics.

3. Automated Workflows

Built-in end-to-end workflows (run_workflow) for research and engineering tasks:

• Sim Gen & Eval (sim_gen_eval): One-shot pipeline: "generate network -> generate demand -> route computation -> simulation -> analysis".
  • Params: grid_number (aliases: grid_size, size), sim_seconds (aliases: steps, duration, end_time), output_dir
• Signal Optimization (signal_opt): Full pipeline: "baseline simulation -> optimization -> optimized simulation -> comparison" with automatic handling of <additional> outputs.
  • Params: net_file (required), route_file (required), sim_seconds (aliases: steps, duration), use_coordinator, output_dir
• RL Training (rl_train): Reinforcement learning training for built-in scenarios. For custom network training, use manage_rl_task/train_custom (based on sumo-rl; network must contain traffic lights; explicitly setting SUMO_HOME is recommended).
  • Params: scenario_name (alias: scenario), episodes (alias: num_episodes), steps (alias: steps_per_episode), output_dir

For detailed parameters and examples, see API documentation.

---

Requirements

• OS: Windows / Linux / macOS
• Python: 3.10+
• SUMO: Eclipse SUMO (SUMO_HOME recommended; SUMO binaries should be available in PATH)

Python Dependencies

Runtime dependencies (required for all MCP tools):

• mcp[cli]>=1.0.0
• sumolib>=1.20.0
• traci>=1.20.0
• sumo-rl>=1.4.3
• pandas>=2.0.0
• requests>=2.31.0

Development dependencies (optional):

• mypy>=1.8.0
• flake8>=7.0.0
• pytest>=8.0.0
• psutil>=5.9.0
• types-*

On Windows, ./install_deps.ps1 -NoDev installs runtime dependencies only.

---

Installation

1. Get the Code

Option A: clone from GitHub (recommended)

git clone https://github.com/XRDS76354/SUMO-MCP-Server.git
cd sumo-mcp

Option B: download ZIP

1. Visit the GitHub repository.
2. Click Code -> Download ZIP.
3. Extract and enter the project folder.

Option C: install as dependency (WIP)

pip install git+https://github.com/XRDS76354/SUMO-MCP-Server.git

2. Install and Configure SUMO

This project depends on Eclipse SUMO.

Important notes:

• If you only use SUMO binaries (sumo, netconvert, netgenerate, duarouter, od2trips, ...), make sure they are in PATH.
• If you use SUMO tool scripts (randomTrips.py, osmGet.py, tls*.py, ...), ensure <SUMO_HOME>/tools is discoverable. Setting SUMO_HOME to your SUMO install directory and adding $SUMO_HOME/bin to PATH is recommended.

Platform-specific setup:

• Windows
  1. Install SUMO using the official installer (docs).
  2. Set environment variables (example):
     • CMD: setx SUMO_HOME "C:\Program Files\Eclipse\sumo", setx PATH "%SUMO_HOME%\bin;%PATH%"
     • PowerShell: $env:SUMO_HOME="C:\Program Files\Eclipse\sumo"; $env:PATH="$env:SUMO_HOME\bin;$env:PATH"
  3. Verify: sumo --version
• Linux (Ubuntu/Debian)
  1. Install: sudo apt-get install sumo sumo-tools
  2. Optional but recommended for tools scripts: export SUMO_HOME=/usr/share/sumo and add $SUMO_HOME/bin to PATH
  3. Verify: sumo --version
• macOS (Homebrew)
  1. Install: brew install sumo
  2. Homebrew usually exposes sumo in PATH; for tools scripts, set SUMO_HOME to .../share/sumo (for example /usr/local/share/sumo or /opt/homebrew/share/sumo)
  3. Verify: sumo --version

For more details, see SUMO official docs.

3. Python Environment

Windows one-click installation

Use the built-in scripts to create .venv and install dependencies (default includes .[dev]).

Option A: PowerShell (recommended)

.\install_deps.ps1

# Optional
.\install_deps.ps1 -NoDev
.\install_deps.ps1 -IndexUrl https://pypi.tuna.tsinghua.edu.cn/simple

Option B: CMD

install_deps.bat

REM Optional
install_deps.bat -NoDev
install_deps.bat -IndexUrl https://pypi.tuna.tsinghua.edu.cn/simple

The scripts will:

• Validate Python 3.10+
• Create .venv if missing
• Upgrade pip/setuptools/wheel
• Install project dependencies in editable mode

Option 1: use uv (recommended)

# 1. Install uv
pip install uv

# 2. Sync dependencies
uv sync

# 3. Activate environment
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

Option 2: Conda + pip

# 1. Create and activate conda env
conda create -n sumo-mcp python=3.10 -y
conda activate sumo-mcp

# 2. Install dependencies
pip install -e ".[dev]" -i https://pypi.tuna.tsinghua.edu.cn/simple

# Runtime-only alternative:
pip install -r requirements.txt

---

Start and Configure

1. Run Locally (for testing)

The server is implemented with mcp.server.fastmcp.FastMCP and communicates over stdio using JSON-RPC 2.0.

Start directly with Python:

python src/server.py

Or use provided startup scripts:

• Linux/macOS: ./start_server.sh
• Windows (PowerShell): .\start_server.ps1
• Windows (CMD): start_server.bat

2. MCP Host Configuration (critical)

When configuring in host apps (Claude Desktop, Trae, Cursor), always use absolute paths.

A. Find required paths

• Python executable
  • Windows (PowerShell): (Get-Command python).Source
  • Linux/macOS: which python
• SUMO_HOME
  • Windows: echo %SUMO_HOME%
  • Linux/macOS: echo $SUMO_HOME

B. Example host config (claude_desktop_config.json)

{
  "mcpServers": {
    "sumo-mcp": {
      "command": "/path/to/your/env/python",
      "args": ["/path/to/sumo-mcp/src/server.py"],
      "env": {
        "SUMO_HOME": "/your/actual/sumo/path",
        "PYTHONPATH": "/path/to/sumo-mcp/src"
      }
    }
  }
}

Important:

1. Replace command with the absolute path of your Python interpreter.
2. Replace args with the absolute path of src/server.py.
3. Explicitly setting SUMO_HOME and PYTHONPATH helps avoid ModuleNotFoundError and environment mismatch issues.

More config samples: mcp_config_examples.json.

---

Prompt Examples

In any MCP-enabled AI assistant, try prompts like:

• Workflow task:

  "Generate a 3x3 grid network, simulate 100 seconds, and report the average speed." (Likely calls run_workflow("sim_gen_eval", {"grid_number": 3, "sim_seconds": 100}))

• Online interaction task:

  "Start simulation for this config and report vehicle speed for ID v_0 each step. Alert me if speed drops below 5 m/s." (Likely calls control_simulation + query_simulation_state)

• RL task:

  "List built-in RL scenarios and train a simple intersection for 5 episodes." (Likely calls manage_rl_task("list_scenarios") + run_workflow("rl_train", {"scenario_name": "...", "episodes": 5}))

• Complex integrated scenario:

  "Use sumo-mcp to generate a 4x4 grid network where all nodes are intersections, spacing 100m, with traffic lights at every intersection. Generate 200 vehicles, run a 1000-second simulation with trajectory recording, then compute average speed for all vehicles over the whole simulation and report it with 2 decimal places."

  Typical execution flow:

  1. manage_network(action="generate", output_file="grid.net.xml", params={"grid": true, "grid_number": 4})
  2. manage_demand(action="random_trips", net_file="grid.net.xml", output_file="trips.xml", params={"end_time": 1000, "period": 5.0})
  3. run_workflow("sim_gen_eval", {"grid_number": 4, "sim_seconds": 1000, "output_dir": "results"}) (or compose online calls manually)
  4. run_analysis(fcd_file="results/fcd.xml")

---

Troubleshooting

• Cannot find sumo (for example: Error: Could not locate SUMO executable ('sumo').)

  1. Run sumo --version in terminal.
  2. If unavailable, add SUMO bin/ to PATH, or set SUMO_HOME and add $SUMO_HOME/bin to PATH.

• Cannot find SUMO tools scripts (randomTrips.py, osmGet.py, tls*.py)

  1. Ensure SUMO_HOME points to the SUMO installation directory.
  2. Ensure <SUMO_HOME>/tools exists and includes required scripts.

• MCP call hangs or host shows undefined

  1. Communication is JSON-RPC over stdio; non-JSON stdout from child processes can corrupt transport.
  2. Upgrade to latest version (TraCI SUMO stdout isolation is included), or ensure child-process stdout is captured/redirected.

• MCP client does not inherit environment variables

  1. Pass explicit env in your MCP host config (mcp_config_examples.json).

Project Structure

sumo-mcp/
├── doc/
│   ├── API.md              # MCP tool API reference (English)
│   ├── API_CN.md           # MCP tool API reference (Chinese)
│   └── sumo-mcp.jpg        # Project image
├── src/
│   ├── server.py           # MCP server entry (FastMCP, aggregated interfaces)
│   ├── utils/              # Common utilities
│   │   ├── connection.py   # TraCI connection manager
│   │   ├── output.py       # Output helpers
│   │   ├── sumo.py         # SUMO config helpers
│   │   ├── timeout.py      # Timeout helpers
│   │   └── traci.py        # TraCI wrappers
│   ├── mcp_tools/          # Core tool modules
│   │   ├── analysis.py     # Analysis tools
│   │   ├── network.py      # Network tools
│   │   ├── route.py        # Routing tools
│   │   ├── signal.py       # Signal tools
│   │   ├── simulation.py   # Simulation control tools
│   │   ├── vehicle.py      # Vehicle tools
│   │   └── rl.py           # Reinforcement learning tools
│   ├── resources/          # Resource files
│   └── workflows/          # Automated workflows
│       ├── sim_gen.py      # Simulation generation workflow
│       ├── signal_opt.py   # Signal optimization workflow
│       └── rl_train.py     # RL training workflow
├── pyproject.toml          # Project config and dependencies
├── requirements.lock       # Locked dependency versions
├── README.md               # Project documentation (English)
└── README_CN.md            # Project documentation (Chinese)

License

MIT License

Media Support

Thanks to the following media platform for coverage:

• BigTrans WeChat Official Account - 重磅开源！SUMO-MCP让大模型助力交通仿真

Contributors

2217173240

gateblues

Hiners

Zpzp1997