SUMO-MCP Server

SUMO-MCP is a middleware that connects large language models to the Eclipse SUMO traffic simulator through the Model Context Protocol (MCP). It enables AI agents to directly invoke SUMO core functions to cover the full workflow from map data acquisition and network generation to demand modeling, simulation execution, and traffic signal optimization. It supports both offline workflows using files and online, real-time TraCI control for micro-level interaction.

How to use

You control SUMO-MCP from an MCP client (for example an AI assistant) to perform end-to-end traffic simulations and analyses. Start by launching the local MCP server and then configure your MCP client to connect to it using the provided stdio interface. You can perform workflow-driven tasks such as network generation, demand generation, route computation, and running simulations, or you can interact with a running simulation in real time to observe vehicle behavior and collect analytics. You can also run automated workflows to generate networks, optimize signals, or train reinforcement learning agents within built-in scenarios.

How to install

Prerequisites you need to prepare before installing and running the MCP server:

• Operating system: Windows, Linux, or macOS
• Python 3.10 or later
• Eclipse SUMO installed and SUMO_HOME configured in your environment
• A working internet connection to install dependencies

Step-by-step commands to set up and run the MCP server locally:

# 1. Clone the project
git clone https://github.com/XRDS76354/SUMO-MCP-Server.git
cd sumo-mcp

# 2. Install Python dependencies (examples use uvx to speed up environment setup)
uvx sync

# 3. Verify Python and SUMO environment
python --version
sumo --version

# 4. Run the MCP server directly for testing
python src/server.py

# Optional: use provided startup scripts for convenience
./start_server.sh
./start_server.ps1
start_server.bat

Environment setup and configuration

Configure environment variables and the MCP client to ensure smooth operation and correct path resolution:

# Example MCP client configuration snippet (absolute paths required)
{
  "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"
      }
    }
  }
}

Managing tools and workflows

SUMO-MCP exposes a comprehensive set of tools to manage networks, demand, signals, simulation, analysis, and reinforcement learning workflows. You can invoke these tools directly from your MCP client to perform common tasks or to chain steps into automated pipelines.

Key capabilities include network management (generate, download_osm, convert), demand management (generate_random, convert_od, compute_routes), traffic signal optimization (cycle_adaptation, coordination), simulation execution (run_simple_simulation), data analysis (run_analysis), online interaction (control_simulation, query_simulation_state), and high-level workflows (run_workflow, sim_gen_eval, signal_opt, rl_train).

Troubleshooting

If you encounter issues starting the MCP server or locating SUMO, verify the following prerequisites and paths. Ensure SUMO binaries are accessible via PATH or SUMO_HOME, and that the MCP server can locate SUMO tools in SUMO_HOME/tools. If environment inheritance fails for the MCP client, explicitly pass necessary env vars in your client configuration.

Available tools

manage_network

Manage road networks with actions to generate, download_osm, and convert network data.

manage_demand

Handle traffic demand with actions to generate random trips, convert OD matrices, and compute routes.

optimize_traffic_signals

Optimize traffic signals using cycle_adaptation and coordination algorithms.

run_simple_simulation

Run standard SUMO simulations with predefined configurations.

run_analysis

Analyze simulation results, including FCD data for speed and movement insights.

control_simulation

Interact with a live or paused simulation via TraCI to step, connect, or disconnect.

query_simulation_state

Query current simulation state such as vehicle lists and global statistics.

run_workflow

Execute end-to-end automated workflows like sim_gen_eval or signal_opt.

rl_train

Train reinforcement learning agents on built-in or custom SUMO scenarios.

manage_rl_task

Set up reinforcement learning tasks, including train_custom for specialized networks.