agentsumo-mcp

agentsumo-mcp

MCP server for SUMO (Simulation of Urban MObility) traffic simulation. Orchestrate network extraction, trip generation, scenario customization, simulation runs, and SQL-based result analysis from any MCP-compatible LLM client.

Features

• Pipeline tools: OSM extraction -> network conversion -> trip generation -> route generation -> simulation
• Scenario customization: edge editing, lane reduction, speed limit changes, vehicle generation, traffic-light timing
• Result analysis: ingest tripinfo / edgedata / summary XML into SQLite for natural-language SQL queries
• Visualization: network plots, edge data heatmaps, policy-target visualizations
• Geocoding: place name -> coordinate -> nearest edge resolution

Requirements

• Python 3.10 or later
• SUMO installed locally (SUMO_HOME environment variable set)

Installation

pip install agentsumo-mcp

Or run without installing via uvx:

uvx agentsumo-mcp

Configuration

Set SUMO_HOME to point at your local SUMO installation:

export SUMO_HOME=/path/to/sumo

On macOS with the official SUMO installer this is usually /Library/Frameworks/EclipseSUMO.framework/Versions/<version>/EclipseSUMO.

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "agentsumo": {
      "command": "uvx",
      "args": ["agentsumo-mcp"],
      "env": {
        "SUMO_HOME": "/path/to/sumo"
      }
    }
  }
}

Usage with other MCP clients

Any MCP client that supports stdio transport works:

agentsumo-mcp

Tools

The server exposes ~25 tools across five categories:

Category	Examples
Network	osm_extract, net_convert, network_summary_tool
Trips & routes	trip_generate, route_generate, vehicle_generation_tool, flow_generation_tool
Customization	edge_edit_tool, reduce_lanes_tool, speed_limit_edit_tool, tls_offset_tool, tls_adaptation_tool
Simulation	sumo_runner
Analysis	xml_to_sqlite_tool, simulation_report_tool, route_analysis_tool, analyze_road_details_tool
Visualization	visualize_net_tool, visualize_edge_tool, visualize_edgedata_tool

Each tool returns structured JSON suitable for downstream LLM reasoning.

Citation

If you use AgentSUMO in academic work, please cite:

@article{jeong2025agentsumo,
  title         = {AgentSUMO: An Agentic Framework for Interactive Simulation Scenario Generation in SUMO via Large Language Models},
  author        = {Jeong, Minwoo and Chang, Jeeyun and Yoon, Yoonjin},
  journal       = {arXiv preprint arXiv:2511.06804},
  year          = {2025},
  url           = {https://arxiv.org/abs/2511.06804}
}

License

MIT. See LICENSE.