AgentSUMO — Claude Code MCP server: what it does, how to install
Bridges LLMs with the SUMO traffic simulator to design scenarios and run traffic models using plain text prompts.
claude mcp add --env SUMO_HOME=<SUMO_HOME> --env AGENTSUMO_MCP_OUTPUT_BASE=<AGENTSUMO_MCP_OUTPUT_BASE> --transport stdio agentsumo -- uvx agentsumo-mcpWhat AgentSUMO does
The server supplies 26 tools for traffic modeling. It extracts networks from OpenStreetMap, creates vehicle trips, compiles routes, and runs simulations. Infrastructure interventions include lane closures and traffic light schedule adjustments.
Simulation outputs convert from XML directly into SQLite tables. Users can inspect metrics through auto-generated HTML summaries. The tools also plot heatmap overlays for congested road segments.
Running simulations requires a local SUMO 1.24+ installation with SUMO_HOME exported. Without the simulator binaries, execution tools fail immediately.
What it helps with
- Build runnable SUMO traffic networks using OpenStreetMap exports
- Simulate road closures, lane reductions, and traffic light schedule shifts
- Transform raw SUMO XML outputs into queryable SQLite databases
- Produce visual HTML reports with congestion heatmaps for road segments
Example prompts for the agent
- Generate a baseline SUMO network and trip routes from an OpenStreetMap bounding box
- Simulate a lane closure on the main avenue and show congestion changes
- Convert recent simulation XML logs into SQLite and create an HTML summary
How to install AgentSUMO
Platform CLI
claude mcp add --env SUMO_HOME=<SUMO_HOME> --env AGENTSUMO_MCP_OUTPUT_BASE=<AGENTSUMO_MCP_OUTPUT_BASE> --transport stdio agentsumo -- uvx agentsumo-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agentsumo-mcp <command>
Platform CLI
codex mcp add agentsumo --env SUMO_HOME=<SUMO_HOME> --env AGENTSUMO_MCP_OUTPUT_BASE=<AGENTSUMO_MCP_OUTPUT_BASE> -- uvx agentsumo-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agentsumo-mcp <command>
Config file
{
"mcpServers": {
"agentsumo": {
"command": "uvx",
"args": [
"agentsumo-mcp"
],
"env": {
"SUMO_HOME": "<SUMO_HOME>",
"AGENTSUMO_MCP_OUTPUT_BASE": "<AGENTSUMO_MCP_OUTPUT_BASE>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agentsumo-mcp <command>
Config file
{
"servers": {
"agentsumo": {
"type": "stdio",
"command": "uvx",
"args": [
"agentsumo-mcp"
],
"env": {
"SUMO_HOME": "<SUMO_HOME>",
"AGENTSUMO_MCP_OUTPUT_BASE": "<AGENTSUMO_MCP_OUTPUT_BASE>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agentsumo-mcp <command>
Platform CLI
gemini mcp add -e SUMO_HOME=<SUMO_HOME> -e AGENTSUMO_MCP_OUTPUT_BASE=<AGENTSUMO_MCP_OUTPUT_BASE> agentsumo uvx agentsumo-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agentsumo-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about AgentSUMO
How to install AgentSUMO in Claude Code?
Run claude mcp add agentsumo-mcp -e SUMO_HOME=<SUMO_HOME> -- uvx agentsumo-mcp with your local SUMO directory path.
What does AgentSUMO do?
It lets coding agents configure road networks, simulate traffic demand, tweak signals, and analyze congestion logs in SUMO.
What prerequisites are needed before setup?
You must have Python 3.10+ and a local SUMO 1.24+ setup with the SUMO_HOME environment variable defined.
