CS2MCP — An MCP Server for Cities: Skylines II

English | 简体中文

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.

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):

Using with Claude

Claude Code: .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 <repo-path>\mcp-server\dist\index.js

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cs2": {
      "command": "node",
      "args": ["<repo-path>\\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

City data

Construction

Finance & policy

Time & meta

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