AgentSUMO

io.github.mw-jeongPublished by GitHub account mw-jeongv0.1.2Updated Oct 24, 2026

MCP server for LLM-driven SUMO traffic simulation, scenario design, and result analysis.

VerifiedSTDIODesktop onlyLocation & LifestyleDeveloper ToolsData & Analytics

Overview

AI-generated overview

AgentSUMO lets an assistant build, run and analyze SUMO traffic simulations from natural-language policy questions, from OSM network creation to reports.

What you can do
Build baseline simulations: extract OSM data, convert networks, generate trips and routes, and run SUMO simulations (Scenario Generation). Apply policy interventions such as edge edits, lane reductions, demand and flow changes, and traffic-signal offset or adaptation (Policy Experimentation). Convert SUMO XML output to SQLite and render HTML simulation reports (Result Analysis). Visualize networks, highlighted edges, policy targets and per-edge metric heatmaps (Visualization). Inspect network statistics, analyze routes, resolve road names to edge IDs, validate origin-destination coordinates and run web-search grounding (Utility Functions).
When to use it
Useful when you want to explore traffic-policy questions, such as road closures, lane reductions, signal optimization or demand changes, as runnable SUMO scenarios and compare results across runs without hand-writing SUMO configuration files.
Requirements
Local Python 3.10+ process, runnable via uvx or pip install; a local SUMO 1.24+ installation with SUMO_HOME pointing at a directory containing bin/, share/ and tools/. The optional AGENTSUMO_MCP_OUTPUT_BASE sets where outputs are written (defaults to the working directory). The full AgentSUMO framework additionally needs an Anthropic Claude API key and a Mapbox token for its web map.
Before you install
Simulations write networks, trips, results and reports to disk under AGENTSUMO_MCP_OUTPUT_BASE or the working directory, so point it at a dedicated folder. The broader framework requires ANTHROPIC_API_KEY and MAPBOX_TOKEN, which are billable third-party credentials; keep them in environment variables or a .env file, not in shared files. The README notes deprecated fallback token files claude_api.txt and mapbox_token.txt.

Installation

In SourceWeft

  1. Open AgentSUMO in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

AgentSUMO

An Agentic Framework for Interactive Simulation Scenario Generation in SUMO via Large Language Models

[PyPI] [tests] [arXiv] [Docs] [License: MIT] [Python 3.10+] [MCP Registry]

[AgentSUMO overview]

Documentation · Installation · Tools · Schema · Tutorials

Overview

AgentSUMO lets non-expert stakeholders design, execute, and analyze SUMO traffic simulations through natural-language interaction. The Planner Agent translates abstract policy questions into executable simulation plans, drives them via the Model Context Protocol (MCP), and surfaces results through a web dashboard.

  • Conversational scenario design — describe a policy question, get a runnable simulation
  • Policy experiments — road closures, lane reductions, signal optimization, demand changes
  • Cross-scenario analysis — SQL-based comparison across runs, with auto-generated HTML reports
  • Web dashboard — geospatial visualization, time-series charts, and trip replay

Demo

[Web interface]

Web interface: conversational planning panel, scenario list, and live simulation status.



[Geospatial visualization]

Geospatial visualization: per-edge metrics, congestion overlays, and trip replay on the 2.5D basemap.

Architecture

User (natural language)    |    vPlanner Agent (Claude LLM, Interactive Planning Protocol)    |    +--> AgentSUMO MCP Client --> AgentSUMO MCP Server (PyPI: agentsumo-mcp) --> SUMO    |    +--> SQLite MCP Client    --> SQLite MCP Server (Anthropic, open source)  --> simulations.db    |    +--> Filesystem MCP Client --> Filesystem MCP Server (Anthropic, open source) --> additional XML files

The reasoning layer (Planner Agent) lives in this repository. The execution layer (agentsumo-mcp) is published to PyPI and installed automatically as a dependency.

Tool Layer

The AgentSUMO MCP Server exposes 26 tools grouped into five capability categories that follow the simulation workflow. Full reference at agentsumo.readthedocs.io/.../tools.

CategoryPurposeRepresentative tools
Scenario GenerationBuild a baseline SUMO simulation: OSM → network → trips → routes → runosm_extract, net_convert, trip_generate, route_generate, sumo_runner
Policy ExperimentationApply infrastructure, demand, and signal-control interventionsedge_edit_tool, reduce_lanes_tool, vehicle_generation_tool, flow_generation_tool, tls_offset_tool, tls_adaptation_tool
Result AnalysisConvert SUMO XML output to SQLite and render HTML reportsxml_to_sqlite_tool, simulation_report_tool
VisualizationRender networks, highlighted edges, and per-edge metric heatmapsvisualize_net_tool, visualize_edge_tool, visualize_policy_target_tool, visualize_edgedata_tool
Utility FunctionsNetwork statistics, routing, road-name ↔ edge-id resolution, OD-coordinate validation, web-search groundingnetwork_summary_tool, route_analysis_tool, validate_od_coordinates_tool, web_search_tool

Installation

Requirements

  • Python 3.10 or later
  • SUMO 1.24 or later (locally installed, with SUMO_HOME set)
  • Anthropic Claude API key (bring-your-own-key)
  • Mapbox access token (used by the web map renderer)

1. Install SUMO

macOS

bash
brew install sumo

Or download the installer from the Eclipse SUMO downloads page.

Windows — Download the installer from the Eclipse SUMO downloads page.

Linux (Ubuntu/Debian)

bash
sudo add-apt-repository ppa:sumo/stablesudo apt-get updatesudo apt-get install sumo sumo-tools sumo-doc

2. Set up the Python environment

Install uv:

bash
# macOS / Linuxcurl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Clone the repository, create a virtual environment, and install AgentSUMO:

bash
git clone https://github.com/mw-jeong/AgentSUMOcd AgentSUMO
# Create a Python 3.12 venvuv venv --python 3.12
# Activate the venvsource .venv/bin/activate              # macOS / Linux# .venv\Scripts\activate               # Windows
# Install AgentSUMO and all dependencies# (this also pulls agentsumo-mcp from PyPI as a dependency)uv pip install -e .

3. Configure environment variables

AgentSUMO reads API keys and the SUMO path from environment variables. The easiest way is a .env file at the project root:

bash
cp .env.example .env

Open .env in your editor and fill in:

ANTHROPIC_API_KEY (required) — Claude API key that drives the Planner Agent. Get one at the Anthropic Console.

ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

MAPBOX_TOKEN (required for the web UI) — used to render the basemap. Get one at the Mapbox access tokens page.

MAPBOX_TOKEN=pk.eyJ1Ijoixxxxxxxxxxxxxxxxxx

SUMO_HOME (required) — absolute path to your local SUMO installation. The directory must contain bin/sumo (or bin/sumo.exe on Windows).

# macOS (Homebrew)SUMO_HOME=/opt/homebrew/share/sumo
# macOS (Eclipse SUMO installer)SUMO_HOME=/Library/Frameworks/EclipseSUMO.framework/Versions/<version>/EclipseSUMO  # e.g. 1.24.0; use the directory name installed under Versions/
# WindowsSUMO_HOME=C:\Program Files (x86)\Eclipse\Sumo
# LinuxSUMO_HOME=/usr/share/sumo

AGENTSUMO_MCP_OUTPUT_BASE (optional) — override the base directory where the MCP server writes simulation outputs (networks, trips, results). Defaults to the current working directory.

AGENTSUMO_MCP_OUTPUT_BASE=/path/to/your/output/dir

4. Run

bash
# Web interface (opens at http://localhost:8000)python web.py
# CLI modepython chat.py
# Clean up simulation outputspython clean.py

Project Structure

AgentSUMO/├── agentsumo/│   ├── agent/        # Planner Agent (Claude orchestrator + prompts)│   ├── client/       # MCP clients (AgentSUMO, SQLite, Filesystem)│   └── core/         # Configuration├── agentsumo_mcp/    # AgentSUMO MCP Server source (also published to PyPI)│   └── defaults/     # Packaged fixtures (e.g., vehicle_types.add.xml)├── packaging/mcp/    # PyPI build configuration for agentsumo-mcp├── web/              # Web interface (FastAPI + Jinja2 templates)├── docs/             # Sphinx documentation source├── tests/            # Unit tests├── assets/           # README images├── output/           # Runtime artifacts (auto-populated; 8 categories tracked│                     #   via .gitkeep — simulations/, networks/, trips/,│                     #   analysis/, reports/, uploads/, visualizations/, additional/)├── chat.py           # CLI entry point├── web.py            # Web server entry point└── .env.example      # Environment variable template

Use the MCP Server Standalone

The AgentSUMO MCP Server can be used independently from this framework with any MCP-compatible LLM client (Claude Desktop, OpenAI tool clients, Gemini, local LLMs):

bash
pip install agentsumo-mcp

Or via uvx without installing:

bash
uvx agentsumo-mcp

The server is registered in the official MCP Registry under io.github.mw-jeong/agentsumo-mcp.

Troubleshooting

SUMO path error — Verify SUMO_HOME in your .env. The directory must contain bin/sumo (or bin/sumo.exe on Windows).

API key error — Verify ANTHROPIC_API_KEY in your .env is set to a valid Claude API key. The Planner Agent will refuse to start without it.

Dependency error — Re-resolve dependencies:

bash
uv pip install -e . --upgrade

Legacy token files (deprecated, scheduled for removal in 0.2.0) — AgentSUMO still falls back to claude_api.txt and mapbox_token.txt at the project root when the corresponding environment variables are missing, but those code paths now emit a DeprecationWarning at import time. Use the .env workflow for new installations.

Documentation

Full documentation lives at agentsumo.readthedocs.io.

  • Installation — SUMO, Python 3.10+, environment setup
  • Tools — reference for all MCP tools
  • Schema — simulations.db ER diagram and column reference
  • Tutorials — walkthroughs of the paper case studies

Citation

If you use AgentSUMO in academic work, please cite:

bibtex
@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.

Developed at

[KAIST]      [CAUS]      [Spatial Tech Innovation Lab]

Source: README.md at commit 2ad1d91

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts