AgentSUMO

io.github.mw-jeong由 GitHub 账号 mw-jeong 发布v0.1.2更新于 Oct 24, 2026

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

已验证STDIO仅桌面位置与生活开发者工具数据与分析

概览

AI 生成的概览

AgentSUMO 让助手根据自然语言提出的政策问题构建、运行并分析 SUMO 交通仿真，从 OSM 路网生成到结果报告。

可以做什么
构建基线仿真：提取 OSM 数据、转换路网、生成出行与路径，并运行 SUMO 仿真（场景生成）。施加政策干预，如边编辑、减少车道、需求与流量调整、信号配时偏移或自适应（政策实验）。将 SUMO XML 输出转换为 SQLite 并生成 HTML 仿真报告（结果分析）。可视化路网、高亮边、政策目标以及按边的指标热力图（可视化）。查看路网统计、分析路径、将道路名称解析为边 ID、校验起讫点坐标，并进行网络搜索佐证（实用工具）。
适用场景
适合把道路封闭、减少车道、信号优化或需求变化等交通政策问题转化为可运行的 SUMO 场景，并在多次运行之间比较结果，而无需手写 SUMO 配置文件。
运行要求
本地 Python 3.10+ 进程，可通过 uvx 或 pip install 运行；需本地安装 SUMO 1.24+，并将 SUMO_HOME 指向包含 bin/、share/ 和 tools/ 的目录。可选的 AGENTSUMO_MCP_OUTPUT_BASE 指定输出位置（默认为当前工作目录）。完整 AgentSUMO 框架另需 Anthropic Claude API 密钥和用于网页地图的 Mapbox 令牌。
安装前请注意
仿真会在 AGENTSUMO_MCP_OUTPUT_BASE 或工作目录下写入路网、出行、结果和报告文件，建议指向专用目录。完整框架需要 ANTHROPIC_API_KEY 和 MAPBOX_TOKEN，这些是会产生费用的第三方凭据，应放在环境变量或 .env 文件中，不要写入共享文件。README 提到已弃用的回退令牌文件 claude_api.txt 和 mapbox_token.txt。

安装

在 SourceWeft 中

  1. 打开 控制台中的 AgentSUMO，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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]

来源：README.md，提交 2ad1d91

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.1.2最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分