# AgentSUMO

Bridges LLMs with the SUMO traffic simulator to design scenarios and run traffic models using plain text prompts.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 11
- Author: urban-ai-institute
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/urban-ai-institute/kra35-prismx-agentsumo
- Updated: 2026-06-17
- HTML: https://affpapa.org/en/nevibecode/mcp/agentsumo

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `SUMO_HOME`, `AGENTSUMO_MCP_OUTPUT_BASE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env SUMO_HOME=<SUMO_HOME> --env AGENTSUMO_MCP_OUTPUT_BASE=<AGENTSUMO_MCP_OUTPUT_BASE> --transport stdio agentsumo -- uvx agentsumo-mcp
```
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>

### Codex

**Platform CLI**
```bash
codex mcp add agentsumo --env SUMO_HOME=<SUMO_HOME> --env AGENTSUMO_MCP_OUTPUT_BASE=<AGENTSUMO_MCP_OUTPUT_BASE> -- uvx agentsumo-mcp
```
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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e SUMO_HOME=<SUMO_HOME> -e AGENTSUMO_MCP_OUTPUT_BASE=<AGENTSUMO_MCP_OUTPUT_BASE> agentsumo uvx agentsumo-mcp
```
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>

## When to use it
- 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
- 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

## Similar
- [Statistics Canada MCP Server](https://affpapa.org/en/nevibecode/mcp/statistics-canada-mcp-server.md) — MCP server · ★ 7
- [zotero-bridge](https://affpapa.org/en/nevibecode/mcp/zotero-bridge.md) — MCP server · ★ 10
- [pp-espn](https://affpapa.org/en/nevibecode/skills/pp-espn.md) — skill · 3800 installs
- [ontology](https://affpapa.org/en/nevibecode/skills/ontology.md) — skill · 3700 installs
- [pp-movie-goat](https://affpapa.org/en/nevibecode/skills/pp-movie-goat.md) — skill · 3400 installs
- [datapackage](https://affpapa.org/en/nevibecode/skills/datapackage.md) — skill · 2100 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md