{"id":"7554cdbb-d072-4b4b-af1c-9771c878822d","slug":"civ6-mcp","kind":"mcp","name":"civ6-mcp","summary":"An MCP server that lets LLM agents play Civilization VI.","owner":"lmwilki","repoUrl":"https://github.com/lmwilki/civ6-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":214,"match":null,"fewStars":false,"format":"mcp","createdAt":null,"addedAt":"2026-10-14T03:43:12.964Z","logoUrl":"https://avatars.githubusercontent.com/u/26510315?u=1bb376d7e7c558440eb71b4a960a157b0545fa97&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra"],"tags":["agentic-ai","agentic-harness","civilization-6","civilization-vi","game","benchmark","llm","python"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T03:53:08.823Z","sample":false,"url":"https://conduits.dev/tools/civ6-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"civ6-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# civ6-mcp\n\nAn MCP server that lets LLM agents play full games of Civilization VI.\n\nConnect any MCP-compatible client — Claude Code, Codex, Gemini CLI, or your own — to a running Civ 6 game. The agent reads game state, moves units, manages cities, conducts diplomacy, and ends turns, all through the game's own rule-enforcing APIs. No cheats, no vision model required.\n\n<!-- TODO: Add screenshot or GIF of agent playing -->\n\n## Capabilities\n\n76 tools covering the full gameplay loop:\n\n- **Units** — list, move, attack, fortify, found cities, build improvements, promote, upgrade\n- **Cities** — inspect, set production, purchase units/buildings with gold, manage focus\n- **Map** — explore terrain, resources, fog of war; get settle and district placement advice\n- **Research** — browse tech and civic trees, set research targets\n- **Diplomacy** — relationships, modifiers, delegations, embassies, alliances, peace deals\n- **Trade** — propose and respond to deals, manage trade routes and destinations\n- **Government** — swap policy cards, change governments, choose era dedications\n- **Governors** — appoint, assign to cities, promote\n- **Religion** — found pantheons and religions, select beliefs, track spread\n- **Great People** — recruit, patronize, reject\n- **World Congress** — vote on resolutions, manage diplomatic favor\n- **Victory** — track progress across all victory conditions\n- **Game lifecycle** — save, load, launch, restart, kill\n\nEvery turn, `end_turn` takes before/after snapshots and reports what happened: units damaged, cities grew, production completed, threats spotted near your cities.\n\n## Quick start\n\n### 1. Configure Civ 6\n\nEnable the FireTuner debug interface and configure recommended settings:\n\n| Setting | Value | Why |\n|---------|-------|-----|\n| **Tuner** | Enabled | Required — opens the TCP debug port the MCP server connects to. Disables achievements. |\n| **Auto End Turn** | Disabled | The agent controls when turns end. Auto-end interferes with the blocker resolution flow. |\n| **Windowed mode** | Recommended | Lets you watch the game while the agent plays. Required for OCR-based save loading. |\n\n**Windows:** All three settings are available in the in-game Options menu. The Tuner setting appears as \"Tuner (disables achievements)\" under gameplay options.\n\n**macOS:** The Tuner setting is not exposed in the menu. Edit `AppOptions.txt` directly and set `EnableTuner 1`:\n\n```\n~/Library/Application Support/Sid Meier's Civilization VI/Firaxis Games/Sid Meier's Civilization VI/AppOptions.txt\n```\n\n**Linux:** Same as macOS — edit `AppOptions.txt` directly and set `EnableTuner 1`:\n\n```\n~/.local/share/aspyr-media/Sid Meier's Civilization VI/AppOptions.txt\n```\n\n<details>\n<summary><strong>Windows: additional setup</strong></summary>\n\n**Install the Civ 6 SDK** — the tuner server is part of the SDK, not the base game:\n1. In Steam, go to Library → filter by Tools\n2. Find and install \"Sid Meier's Civilization VI SDK\"\n\n**Important notes:**\n- Close `FireTuner.exe` (the SDK's GUI tool) before running civ6-mcp — the game only allows **one** tuner connection at a time\n- Do **not** run from WSL — the network bridging between WSL2 and Windows is unreliable and the tuner server locks up after failed connections\n- If the connection fails, **restart the game** — the tuner often hangs after a bad handshake and won't recover until the process is recycled\n</details>\n\n<details>\n<summary><strong>Linux: additional notes</strong></summary>\n\n- The **native Linux port** is required — the FireTuner debug interface is built into the native binary. Proton/Wine builds do not expose it.\n- The game runs as a single `Civ6` process launched via Steam Linux Runtime (scout-on-soldier).\n- GUI automation (OCR-based menu navigation) requires **X11**. On Wayland, the game typically runs under XWayland which should work, but a native X11 session is most reliable.\n</details>\n\nRestart Civ 6. The game will listen on TCP port 4318 for connections.\n\n### 2. Install\n\n```bash\ngit clone https://github.com/lmwilki/civ6-mcp.git\ncd civ6-mcp\nuv sync\n```\n\nFor GUI automation features (screenshot, OCR-based menu navigation):\n\n```bash\n# macOS\nuv pip install 'civ6-mcp[launcher-macos]'\n\n# Windows (uses built-in Windows OCR — no external binaries needed)\nuv pip install 'civ6-mcp[launcher-windows]'\n\n# Linux (Ubuntu/Debian)\nsudo apt install xdotool tesseract-ocr\nuv pip install 'civ6-mcp[launcher-linux]'\n```\n\n### 3. Test the connection\n\nWith Civ 6 running and a game loaded:\n\n```bash\nuv run python scripts/test_connection.py\n```\n\nYou should see a successful handshake and a list of Lua states (GameCore_Tuner, InGame, etc.).\n\n### 4. Configure your MCP client\n\nThe server runs over stdio. Point your client at it:\n\n<details>\n<summary><strong>Claude Code</strong></summary>\n\nThe repo includes `.mcp.json` — detected automatically:\n\n```bash\ncd civ6-mcp\nclaude\n```\n</details>\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\nAdd to your config file:\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"civ6\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/civ6-mcp\", \"civ-mcp\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Codex</strong></summary>\n\nAdd to `.codex/config.toml` in the project root:\n\n```toml\n[mcp_servers.civ6]\ncommand = \"uv\"\nargs = [\"run\", \"--directory\", \"/path/to/civ6-mcp\", \"civ-mcp\"]\n```\n</details>\n\n<details>\n<summary><strong>Gemini CLI</strong></summary>\n\nAdd to `.gemini/settings.json` in the project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"civ6\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/civ6-mcp\", \"civ-mcp\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Other MCP clients</strong></summary>\n\nThe server speaks stdio JSON-RPC:\n\n```bash\nuv run civ-mcp\n```\n</details>\n\n### 5. Play\n\nLoad a game in Civ 6, connect your client, and try:\n\n```\nPlay my Civ 6 game. Start by getting an overview, then check units and\ncities, and play through the turn.\n```\n\nThe agent will orient with `get_game_overview`, scan the map for threats, move units, set production and research, handle diplomacy, and end the turn.\n\n## As a benchmark\n\nCivilization VI is a compelling environment for evaluating LLM strategic reasoning. Games run 300+ turns with compounding decisions, incomplete information, and multiple competing objectives — a significant step up from single-turn or short-horizon tasks.\n\n- **Multi-turn planning** — decisions compound over hundreds of turns with delayed payoffs\n- **Incomplete information** — fog of war, hidden AI intentions, unexplored map\n- **Resource management** — balancing gold, production, science, culture, faith, and military\n- **Opponent modeling** — reading diplomatic signals, anticipating AI behavior\n- **Strategic adaptation** — responding to threats, shifting priorities mid-game\n\nThe MCP interface provides a clean abstraction: the model receives narrated game state as text and responds with tool calls. All game rules are enforced by the engine. A companion web app lets you replay sessions turn by turn.\n\n## How it works\n\n```\nClaude / Any MCP Client\n    |  stdio (JSON-RPC)\n    v\nMCP Server (Python)    <- 70+ tools\n    |\n    |  Generates Lua code at runtime\n    |  TCP :4318\n    v\nCivilization VI        <- Game is the TCP server\n```\n\nThe server maintains a persistent TCP connection to Civ 6 via the FireTuner debug protocol. It generates Lua code, executes it inside the game's two Lua VMs (GameCore for reading state, InGame for issuing commands), parses the output, and returns narrated text to the LLM.\n\nThe repo includes an [AGENTS.md](AGENTS.md) playbook (symlinked as `CLAUDE.md` for Claude Code) with detailed instructions for agents: turn loop, combat, diplomacy, common pitfalls. See the [devlog](docs/devlog/) for the full development story, including reverse-engineering the FireTuner protocol and the many API quirks discovered along the way.\n\n## Requirements\n\n- **macOS, Windows, or Linux** with Civilization VI (Steam version, Gathering Storm DLC)\n- **Python 3.12+** with [uv](https://docs.astral.sh/uv/)\n- An **MCP client** (Claude Code, Codex, Gemini CLI, or any MCP-compatible client)\n\n## License\n\nMIT\n"}