SUMO交通模拟中间件

SUMO-MCP:SUMO流量模拟的MCP服务器（面向LLM）

中文文档

SUMO-MCP是一个中间件层，将大型语言模型（LLM）与 日蚀SUMO 交通模拟。通过 模型上下文协议（MCP），AI代理（如Claude、Cursor和TRAE）可以直接调用SUMO功能，实现跨平台的端到端自动化 OpenStreetMap数据检索, 网络生成, 需求建模, 模拟执行，以及 信号优化.

系统同时支持这两种功能 脱机工作流 （基于文件的管道）和 在线交互 （实时TraCI控制），涵盖从宏观规划到微观控制的用例。

API参考： doc/API.md （唯一的真相来源仍然是工具注册 src/server.py).

核心功能

1.统一的工具链

核心MCP接口分为直观的工具，以简化常见的SUMO操作：

• 网络管理(manage_network)：生成网络(generate)，下载OSM数据(download_osm)，并转换格式(convert).
• 需求管理(manage_demand)：生成随机行程(generate_random)，转换OD矩阵(convert_od)，并计算路线(compute_routes).
• 信号优化(optimize_traffic_signals)：包括周期适应(cycle_adaptation)以及协调(coordination). cycle_adaptation 输出SUMO <additional> 信号计划（自动安装到 <additional-files> 按工作流）。
• 模拟与分析：运行基于标准配置的模拟(run_simple_simulation)FCD轨迹分析(run_analysis).

一些聚合工具接受 params.options: list[str]，它们逐个标记地附加到底层SUMO二进制文件/脚本中（请参阅中的“通用约定” doc/API.md).

2.在线互动

通过TraCI实现实时控制，实现细粒度闭环操作：

• 仿真控制(control_simulation)：连接(connect)，步骤(step)，并干净地断开连接(disconnect).
• 状态查询(query_simulation_state)：获取活动车辆ID(vehicle_list)，每辆车的变量(vehicle_variable)，以及全局模拟统计。

3.自动化工作流程

内置端到端工作流(run_workflow)用于研究和工程任务：

• 生成和评估sim_gen_eval)：一次性管道：“生成网络->生成需求->路线计算->模拟->分析”。
  • 参数： grid_number （别名： grid_size, size), sim_seconds （别名： steps, duration, end_time), output_dir
• 信号优化(signal_opt)：全流程：“基线模拟->优化->优化模拟->比较”，自动处理 <additional> 输出。
  • 参数： net_file （必填）， route_file （必填）， sim_seconds （别名： steps, duration), use_coordinator, output_dir
• RL培训(rl_train)：针对内置场景的强化学习培训。对于自定义网络培训，请使用 manage_rl_task/train_custom （基于 相扑rl网络必须包含交通信号灯；显式设置 SUMO_HOME 推荐）。
  • 参数： scenario_name （别名： scenario), episodes （别名： num_episodes), steps （别名： steps_per_episode), output_dir

有关详细参数和示例，请参阅 API文档.

需求

• 操作系统：Windows/Linux/macOS
• python: 3.10+
• 苏摩: 日蚀SUMO (SUMO_HOME 推荐；SUMO二进制文件应可在 PATH)

Python依赖关系

运行时依赖关系（所有MCP工具都需要）：

• mcp[cli]>=1.0.0
• sumolib>=1.20.0
• traci>=1.20.0
• sumo-rl>=1.4.3
• pandas>=2.0.0
• requests>=2.31.0

开发依赖关系（可选）：

• mypy>=1.8.0
• flake8>=7.0.0
• pytest>=8.0.0
• psutil>=5.9.0
• types-*

在Windows上， ./install_deps.ps1 -NoDev 仅安装运行时依赖项。

安装

1.获取代码

选项A：从GitHub克隆（推荐）

git clone https://github.com/XRDS76354/SUMO-MCP-Server.git
cd sumo-mcp

选项B：下载ZIP

1. 访问 GitHub 仓库.
2. 点击 代码 -> 下载 ZIP.
3. 提取并输入项目文件夹。

选项C：作为依赖项安装（WIP）

pip install git+https://github.com/XRDS76354/SUMO-MCP-Server.git

2.安装和配置SUMO

该项目取决于 日蚀SUMO.

重要提示：

• 如果只使用SUMO二进制文件(sumo, netconvert, netgenerate, duarouter, od2trips, ...），确保他们在 PATH.
• 如果您使用SUMO工具脚本(randomTrips.py, osmGet.py, tls*.py, ...），确保 <SUMO_HOME>/tools 是可发现的。设置 SUMO_HOME 到SUMO安装目录并添加 $SUMO_HOME/bin 到 PATH 是推荐的。

平台特定设置：

• 视窗
  1. 使用官方安装程序安装SUMO(文档).
  2. 设置环境变量（示例）：
     • CMD: setx SUMO_HOME "C:\Program Files\Eclipse\sumo", setx PATH "%SUMO_HOME%\bin;%PATH%"
     • PowerShell： $env:SUMO_HOME="C:\Program Files\Eclipse\sumo"; $env:PATH="$env:SUMO_HOME\bin;$env:PATH"
  3. 验证： sumo --version
• Linux（Ubuntu/Debian）
  1. 安装： sudo apt-get install sumo sumo-tools
  2. 可选，但建议用于工具脚本： export SUMO_HOME=/usr/share/sumo 并添加 $SUMO_HOME/bin 到 PATH
  3. 验证： sumo --version
• macOS（自制）
  1. 安装： brew install sumo
  2. 自制啤酒通常会暴露 sumo 在 PATH；对于工具脚本，请设置 SUMO_HOME 到 .../share/sumo （例如 /usr/local/share/sumo 或 /opt/homebrew/share/sumo)
  3. 验证： sumo --version

有关更多详细信息，请参阅 SUMO官方文件.

3.Python环境

Windows一键安装

使用内置脚本创建 .venv 和安装依赖项（默认包括 .[dev]).

选项A：PowerShell（推荐）

.\install_deps.ps1

# Optional
.\install_deps.ps1 -NoDev
.\install_deps.ps1 -IndexUrl https://pypi.tuna.tsinghua.edu.cn/simple

选项B:CMD

install_deps.bat

REM Optional
install_deps.bat -NoDev
install_deps.bat -IndexUrl https://pypi.tuna.tsinghua.edu.cn/simple

脚本将：

• 验证Python 3.10+
• 创建 .venv 如果丢失
• 升级pip/setuptools/wheel
• 在可编辑模式下安装项目依赖项

选项1：使用紫外线（推荐）

# 1. Install uv
pip install uv

# 2. Sync dependencies
uv sync

# 3. Activate environment
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

选项2：康达+点

# 1. Create and activate conda env
conda create -n sumo-mcp python=3.10 -y
conda activate sumo-mcp

# 2. Install dependencies
pip install -e ".[dev]" -i https://pypi.tuna.tsinghua.edu.cn/simple

# Runtime-only alternative:
pip install -r requirements.txt

启动和配置

1.本地运行（用于测试）

服务器是通过以下方式实现的 mcp.server.fastmcp.FastMCP 并使用JSON-RPC 2.0通过stdio进行通信。

直接从Python开始：

python src/server.py

或者使用提供的启动脚本：

• Linux/macOS： ./start_server.sh
• Windows（PowerShell）： .\start_server.ps1
• Windows（CMD）： start_server.bat

2.MCP主机配置（关键）

在主机应用程序（Claude Desktop、Trae、Cursor）中配置时，始终使用绝对路径。

A.找到所需的路径

• Python可执行文件
  • Windows（PowerShell）： (Get-Command python).Source
  • Linux/macOS： which python
• SUMO_HOME
  • 窗户： echo %SUMO_HOME%
  • Linux/macOS： echo $SUMO_HOME

B.主机配置示例(claude_desktop_config.json)

{
  "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"
      }
    }
  }
}

重要提示：

1. 替换 command 使用Python解释器的绝对路径。
2. 替换 args 与绝对路径 src/server.py.
3. 明确设置 SUMO_HOME 和 PYTHONPATH 有助于避免 ModuleNotFoundError 以及环境不匹配问题。

更多配置示例： mcp_config_examples.json.

提示示例

在任何启用MCP的AI助手中，尝试以下提示：

• 工作流任务：

  “生成一个3x3网格网络，模拟100秒，并报告平均速度。” （可能的电话 run_workflow("sim_gen_eval", {"grid_number": 3, "sim_seconds": 100}))

• 在线互动任务：

  “启动此配置的模拟，并报告ID的车速 v_0 每一步。如果速度降至5 m/s以下，请提醒我。” （可能的电话 control_simulation + query_simulation_state)

• RL任务：

  “列出内置的强化学习场景，并为5集训练一个简单的交集。” （可能的电话 manage_rl_task("list_scenarios") + run_workflow("rl_train", {"scenario_name": "...", "episodes": 5}))

• 复杂的集成场景：

  “使用sumo-mcp生成一个4x4网格网络，其中所有节点都是交叉口，间距为100米，每个交叉口都有交通灯。生成200辆车，运行1000秒的轨迹记录模拟，然后计算整个模拟过程中所有车辆的平均速度，并用2位小数报告。”

  典型执行流程：

  1. manage_network(action="generate", output_file="grid.net.xml", params={"grid": true, "grid_number": 4})
  2. manage_demand(action="random_trips", net_file="grid.net.xml", output_file="trips.xml", params={"end_time": 1000, "period": 5.0})
  3. run_workflow("sim_gen_eval", {"grid_number": 4, "sim_seconds": 1000, "output_dir": "results"}) （或手动拨打在线电话）
  4. run_analysis(fcd_file="results/fcd.xml")

故障排除

• 找不到 sumo （例如： Error: Could not locate SUMO executable ('sumo').)

  1. 跑 sumo --version 在终端。
  2. 如果不可用，请添加SUMO bin/ 到 PATH，或设置 SUMO_HOME 并添加 $SUMO_HOME/bin 到 PATH.

• 找不到SUMO工具脚本(randomTrips.py, osmGet.py, tls*.py)

  1. 确保 SUMO_HOME 指向SUMO安装目录。
  2. 确保 <SUMO_HOME>/tools 存在并包含所需的脚本。

• MCP呼叫挂起或主机显示 undefined

  1. 通过stdio进行JSON-RPC通信；子进程中的非JSON stdout可能会损坏传输。
  2. 升级到最新版本（包括TraCI SUMO stdout隔离），或确保捕获/重定向子进程stdout。

• MCP客户端不继承环境变量

  1. 明确传递 env 在MCP主机配置中(mcp_config_examples.json).

项目结构

sumo-mcp/
├── doc/
│   ├── API.md              # MCP tool API reference (English)
│   ├── API_CN.md           # MCP tool API reference (Chinese)
│   └── sumo-mcp.jpg        # Project image
├── src/
│   ├── server.py           # MCP server entry (FastMCP, aggregated interfaces)
│   ├── utils/              # Common utilities
│   │   ├── connection.py   # TraCI connection manager
│   │   ├── output.py       # Output helpers
│   │   ├── sumo.py         # SUMO config helpers
│   │   ├── timeout.py      # Timeout helpers
│   │   └── traci.py        # TraCI wrappers
│   ├── mcp_tools/          # Core tool modules
│   │   ├── analysis.py     # Analysis tools
│   │   ├── network.py      # Network tools
│   │   ├── route.py        # Routing tools
│   │   ├── signal.py       # Signal tools
│   │   ├── simulation.py   # Simulation control tools
│   │   ├── vehicle.py      # Vehicle tools
│   │   └── rl.py           # Reinforcement learning tools
│   ├── resources/          # Resource files
│   └── workflows/          # Automated workflows
│       ├── sim_gen.py      # Simulation generation workflow
│       ├── signal_opt.py   # Signal optimization workflow
│       └── rl_train.py     # RL training workflow
├── pyproject.toml          # Project config and dependencies
├── requirements.lock       # Locked dependency versions
├── README.md               # Project documentation (English)
└── README_CN.md            # Project documentation (Chinese)

许可证

MIT许可证

媒体支持

感谢以下媒体平台的报道：

• BigTrans微信公众号- 重磅开源！SUMO-MCP让大模型助力交通仿真

贡献者