Cities Skylines 2 Mcp

CS2MCP — An MCP Server for Cities: Skylines II

English | [简体中文](README.CHS.md)

Give Claude (or any MCP client) full control over a running Cities: Skylines II game: read city data, drive the camera and take screenshots, build roads and buildings, paint zones, manage finances and policies, and control simulation time.

> 44 MCP tools covering five dimensions — observe / build / tune / govern / time — all verified in-game. An AI can use them to pick a site, build an elevated interchange, zone a residential area, then run the simulation and observe the results. It plays the game the way a player does.

Architecture

Claude Code / Claude Desktop (any MCP client)
      │  MCP (stdio)
      ▼
cs2-mcp  (mcp-server/, Node.js process)
      │  HTTP, localhost-only 127.0.0.1:8642
      ▼
CS2MCP bridge mod  (CS2MCP.Bridge/, inside the game process)
      │  all ECS reads/writes run on the simulation main thread
      ▼
Cities: Skylines II

• In-game mod (C#): runs a minimal HTTP server on a TcpListener bound to 127.0.0.1 inside the game process. Requests are queued by listener threads and executed on the simulation main thread by an ECS system registered at SystemUpdatePhase.UIUpdate (works while paused). Construction goes through a custom ToolBaseSystem using the game's native definition/validation/apply pipeline; demolition goes through the bulldozer pipeline — no entity mutations that bypass game validation.
• MCP server (TypeScript): translates MCP tool calls into HTTP requests against the bridge mod, over stdio transport.

Requirements

• Windows + Cities: Skylines II (Steam)
• .NET SDK 8.0+ (to build the mod)
• Node.js 18+ (to run the MCP server)

Build & Install

# 1. Build the in-game mod (auto-deploys to the game's local Mods folder)
dotnet build CS2MCP.Bridge\CS2MCP.Bridge.csproj

# 2. Build the MCP server
cd mcp-server
npm install
npm run build

The mod deploys to %USERPROFILE%\AppData\LocalLow\Colossal Order\Cities Skylines II\Mods\CS2MCP\ and loads automatically on game start — no Paradox Mods publishing required. To disable it temporarily, rename the folder to .CS2MCP.

Game path configuration

Building the mod references assemblies from the game folder. Resolution order (first match wins):

1. Command line: dotnet build -p:GamePath="X:\...\Cities Skylines II"
2. CS2_PATH environment variable
3. CSII_INSTALLATIONPATH environment variable (set by the official modding toolchain)
4. Auto-probing of common Steam library locations (C:\Program Files (x86)\Steam, Steam / SteamLibrary on common drive letters)

If the game cannot be found the build fails with a clear error. Example:

setx CS2_PATH "D:\Steam\steamapps\common\Cities Skylines II"

Runtime environment variables (.env supported)

The MCP server loads mcp-server/.env via dotenv (see .env.example):

| Variable | Scope | Default | Description | |---|---|---|---| | CS2_BRIDGE_URL | MCP server | http://127.0.0.1:8642 | Address of the bridge mod | | CS2MCP_PORT | game process | 8642 | Bridge listen port (change both together) | | CS2_PATH | build time | auto-probed | Game install folder |

Using with Claude

Claude Code: [.mcp.json](.mcp.json) in the repository root registers the cs2 server — just open Claude Code in the project directory (it asks for trust on first use). To register from another directory:

claude mcp add cs2 -- node \mcp-server\dist\index.js

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cs2": {
      "command": "node",
      "args": ["\\mcp-server\\dist\\index.js"]
    }
  }
}

Start the game, load a save, then ask Claude: "How are my city's finances?", "Zone a residential area by the river", "Build a road connecting the industrial area to the highway".

Tool Reference (44 tools)

State & view

| Tool | Description | |---|---| | cs2_ping | Bridge liveness, mod version, game mode (responds even while loading) | | cs2_game_state | Mode, city name, pause/speed, in-game date & time | | cs2_city_overview | Population, happiness, health, money, XP, date | | cs2_screenshot | Current view as PNG (end-of-frame capture, default 1280px wide) | | cs2_get_camera / cs2_set_camera | Camera read/write (pivot/angles/zoom) — combined with screenshots, the AI's own eyes |

City data

| Tool | Description | |---|---| | cs2_demand | RCI demand + demand factors (internal 0-255 scale; refreshes only while simulating) | | cs2_budget | Budget breakdown: 14 income / 15 expense sources | | cs2_city_services | Electricity, water & sewage, garbage status | | cs2_labor | Employment, unemployment, jobs by education level, age structure | | cs2_statistics | Time series for 60+ statistics (32 samples per in-game day) | | cs2_terrain | Whole-map heightmap + water depth grid | | cs2_gridmap | Native cell-map layers: land value, ground/air/noise pollution, ground water | | cs2_zoning | Zoning summary (occupied/empty per zone type) | | cs2_notifications | All in-world warning icons (no power/water, abandoned...) with target entities | | cs2_inspect | Single-entity detail (residents/employees/status flags) |

Construction

| Tool | Description | |---|---| | cs2_find_prefabs | Search building/road/network/tree prefabs by name | | cs2_place_building | Place buildings/trees (terrain-sampled height, rotation, native validation) | | cs2_build_road | Any network segment: straight / curved via cx,cz / elevated via e1,e2 (bridges, ramps) | | cs2_upgrade_road | Road upgrades: grass/trees/wide sidewalk/sound barrier/parking/lighting/median | | cs2_zone_area / cs2_list_zones | Paint zoning (None to clear) and list zone types | | cs2_demolish | Demolish buildings/segments/trees/districts (bulldozer pipeline) | | cs2_list_buildings / cs2_list_roads / cs2_list_objects | Entity listings (ids, coordinates) |

Finance & policy

| Tool | Description | |---|---| | cs2_get_taxes / cs2_set_tax | Tax rates for the four zone classes (clamped to game limits) | | cs2_policies / cs2_set_policy | City policies (with localized names) | | cs2_service_budgets / cs2_set_service_budget | Per-service budget sliders 50-150% | | cs2_get_fees / cs2_set_fee | Service fees (electricity/water/healthcare/education...) | | cs2_get_loan / cs2_set_loan | Borrow / repay loans | | cs2_list_districts / cs2_create_district | List districts / draw a district polygon | | cs2_district_policies / cs2_set_district_policy | District policies | | cs2_tiles_info | Owned map tiles / upkeep info |

Time & meta

| Tool | Description | |---|---| | cs2_set_simulation | Pause / set speed (0-8) | | cs2_run_simulation | Timed run: simulate N in-game hours, then auto-pause | | cs2_save_game | Trigger a save (recommended before large AI operations) |

Troubleshooting

• cs2_ping unreachable: the mod is not loaded. Check %USERPROFILE%\AppData\LocalLow\Colossal Order\Cities Skylines II\Logs\CS2MCP.log (should contain bridge listening on ...); if the file is missing, check Player.log in the same folder.
• 409 no city loaded: still in the main menu — load a save first.
• Lock states look wrong: unpause briefly once after loading (lock-related endpoints return a stalenessWarning until the simulation has ticked).
• Port conflict: set CS2MCP_PORT for the game process and update CS2_BRIDGE_URL in .env to match.

Known Limitations / Roadmap

• Map tile purchasing, transit line planning and terraforming are not implemented yet (planned for v0.9)
• Ramps can only connect at segment endpoints (nodes); mid-segment smooth merges are not supported yet
• Screenshots capture the game's current rendering: with a road-tool panel open the game renders roads in white outline mode

Disclaimer & Credits

• This is an unofficial community mod, not affiliated with Colossal Order or Paradox Interactive.
• CS2MCP.Bridge/CreateDefinitions.cs is ported from LineTool-CS2 (Apache-2.0, © algernon) and contains portions derived from decompiled game code, subject to the Paradox Interactive User Agreement.
• Thanks to the CS2 modding community — the public code of LineTool, InfoLoom, Traffic, unity-mcp and others made this project possible.

License

[Apache-2.0](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LancerComet
• Source: LancerComet/cities-skylines-2-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.