Skip to content
Back to search

civ6-mcp

An MCP server that lets LLM agents play Civilization VI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lmwilki--civ6-mcp/badge.svg)](/listings/lmwilki--civ6-mcp)

HTML

<a href="/listings/lmwilki--civ6-mcp"><img src="/api/listings/lmwilki--civ6-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Configure Civ 6

Enable the FireTuner debug interface and configure recommended settings:

| Setting | Value | Why | |---------|-------|-----| | **Tuner** | Enabled | Required — opens the TCP debug port the MCP server connects to. Disables achievements. | | **Auto End Turn** | Disabled | The agent controls when turns end. Auto-end interferes with the blocker resolution flow. | | **Windowed mode** | Recommended | Lets you watch the game while the agent plays. Required for OCR-based save loading. |

**Windows:** All three settings are available in the in-game Options menu. The Tuner setting appears as "Tuner (disables achievements)" under gameplay options.

**macOS:** The Tuner setting is not exposed in the menu. Edit `AppOptions.txt` directly and set `EnableTuner 1`:

~/Library/Application Support/Sid Meier's Civilization VI/Firaxis Games/Sid Meier's Civilization VI/AppOptions.txt

**Linux:** Same as macOS — edit `AppOptions.txt` directly and set `EnableTuner 1`:

~/.local/share/aspyr-media/Sid Meier's Civilization VI/AppOptions.txt

<details> <summary><strong>Windows: additional setup</strong></summary>

**Install the Civ 6 SDK** — the tuner server is part of the SDK, not the base game: 1. In Steam, go to Library → filter by Tools 2. Find and install "Sid Meier's Civilization VI SDK"

**Important notes:** - Close `FireTuner.exe` (the SDK's GUI tool) before running civ6-mcp — the game only allows **one** tuner connection at a time - Do **not** run from WSL — the network bridging between WSL2 and Windows is unreliable and the tuner server locks up after failed connections - If the connection fails, **restart the game** — the tuner often hangs after a bad handshake and won't recover until the process is recycled </details>

<details> <summary><strong>Linux: additional notes</strong></summary>

- The **native Linux port** is required — the FireTuner debug interface is built into the native binary. Proton/Wine builds do not expose it. - The game runs as a single `Civ6` process launched via Steam Linux Runtime (scout-on-soldier). - 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. </details>

Restart Civ 6. The game will listen on TCP port 4318 for connections.

2. Install

git clone https://github.com/lmwilki/civ6-mcp.git
cd civ6-mcp
uv sync

For GUI automation features (screenshot, OCR-based menu navigation):

# macOS
uv pip install 'civ6-mcp[launcher-macos]'

# Windows (uses built-in Windows OCR — no external binaries needed)
uv pip install 'civ6-mcp[launcher-windows]'

# Linux (Ubuntu/Debian)
sudo apt install xdotool tesseract-ocr
uv pip install 'civ6-mcp[launcher-linux]'

3. Test the connection

With Civ 6 running and a game loaded:

uv run python scripts/test_connection.py

You should see a successful handshake and a list of Lua states (GameCore_Tuner, InGame, etc.).

4. Configure your MCP client

The server runs over stdio. Point your client at it:

<details> <summary><strong>Claude Code</strong></summary>

The repo includes `.mcp.json` — detected automatically:

cd civ6-mcp
claude

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

Add to your config file: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

{
  "mcpServers": {
    "civ6": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/civ6-mcp", "civ-mcp"]
    }
  }
}

</details>

<details> <summary><strong>Codex</strong></summary>

Add to `.codex/config.toml` in the project root:

[mcp_servers.civ6]
command = "uv"
args = ["run", "--directory", "/path/to/civ6-mcp", "civ-mcp"]

</details>

<details> <summary><strong>Gemini CLI</strong></summary>

Add to `.gemini/settings.json` in the project root:

{

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 232 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # civ6-mcp
  2. An MCP server that lets LLM agents play full games of Civilization VI.
  3. Connect 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.
  4. <!-- TODO: Add screenshot or GIF of agent playing -->
  5. ## Capabilities
  6. 76 tools covering the full gameplay loop:
  7. - **Units** — list, move, attack, fortify, found cities, build improvements, promote, upgrade
  8. - **Cities** — inspect, set production, purchase units/buildings with gold, manage focus
  9. - **Map** — explore terrain, resources, fog of war; get settle and district placement advice
  10. - **Research** — browse tech and civic trees, set research targets
  11. - **Diplomacy** — relationships, modifiers, delegations, embassies, alliances, peace deals
  12. - **Trade** — propose and respond to deals, manage trade routes and destinations
  13. - **Government** — swap policy cards, change governments, choose era dedications
  14. - **Governors** — appoint, assign to cities, promote
  15. - **Religion** — found pantheons and religions, select beliefs, track spread
  16. - **Great People** — recruit, patronize, reject
  17. - **World Congress** — vote on resolutions, manage diplomatic favor
  18. - **Victory** — track progress across all victory conditions
  19. - **Game lifecycle** — save, load, launch, restart, kill
  20. Every turn, `end_turn` takes before/after snapshots and reports what happened: units damaged, cities grew, production completed, threats spotted near your cities.
  21. ## Quick start
  22. ### 1. Configure Civ 6
  23. Enable the FireTuner debug interface and configure recommended settings:
  24. | Setting | Value | Why |
  25. |---------|-------|-----|
  26. | **Tuner** | Enabled | Required — opens the TCP debug port the MCP server connects to. Disables achievements. |
  27. | **Auto End Turn** | Disabled | The agent controls when turns end. Auto-end interferes with the blocker resolution flow. |
  28. | **Windowed mode** | Recommended | Lets you watch the game while the agent plays. Required for OCR-based save loading. |
  29. **Windows:** All three settings are available in the in-game Options menu. The Tuner setting appears as "Tuner (disables achievements)" under gameplay options.
  30. **macOS:** The Tuner setting is not exposed in the menu. Edit `AppOptions.txt` directly and set `EnableTuner 1`:
  31. ```
  32. ~/Library/Application Support/Sid Meier's Civilization VI/Firaxis Games/Sid Meier's Civilization VI/AppOptions.txt
  33. ```
  34. **Linux:** Same as macOS — edit `AppOptions.txt` directly and set `EnableTuner 1`:
  35. ```
  36. ~/.local/share/aspyr-media/Sid Meier's Civilization VI/AppOptions.txt
  37. ```
  38. <details>
  39. <summary><strong>Windows: additional setup</strong></summary>
  40. **Install the Civ 6 SDK** — the tuner server is part of the SDK, not the base game:
  41. 1. In Steam, go to Library → filter by Tools
  42. 2. Find and install "Sid Meier's Civilization VI SDK"
  43. **Important notes:**
  44. - Close `FireTuner.exe` (the SDK's GUI tool) before running civ6-mcp — the game only allows **one** tuner connection at a time
  45. - Do **not** run from WSL — the network bridging between WSL2 and Windows is unreliable and the tuner server locks up after failed connections
  46. - If the connection fails, **restart the game** — the tuner often hangs after a bad handshake and won't recover until the process is recycled
  47. </details>
  48. <details>
  49. <summary><strong>Linux: additional notes</strong></summary>
  50. - The **native Linux port** is required — the FireTuner debug interface is built into the native binary. Proton/Wine builds do not expose it.
  51. - The game runs as a single `Civ6` process launched via Steam Linux Runtime (scout-on-soldier).
  52. - 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.
  53. </details>
  54. Restart Civ 6. The game will listen on TCP port 4318 for connections.
  55. ### 2. Install
  56. ```bash
  57. git clone https://github.com/lmwilki/civ6-mcp.git
  58. cd civ6-mcp
  59. uv sync
  60. ```
  61. For GUI automation features (screenshot, OCR-based menu navigation):
  62. ```bash
  63. # macOS
  64. uv pip install 'civ6-mcp[launcher-macos]'
  65. # Windows (uses built-in Windows OCR — no external binaries needed)
  66. uv pip install 'civ6-mcp[launcher-windows]'
  67. # Linux (Ubuntu/Debian)
  68. sudo apt install xdotool tesseract-ocr
  69. uv pip install 'civ6-mcp[launcher-linux]'
  70. ```
  71. ### 3. Test the connection
  72. With Civ 6 running and a game loaded:
  73. ```bash
  74. uv run python scripts/test_connection.py
  75. ```
  76. You should see a successful handshake and a list of Lua states (GameCore_Tuner, InGame, etc.).
  77. ### 4. Configure your MCP client
  78. The server runs over stdio. Point your client at it:
  79. <details>
  80. <summary><strong>Claude Code</strong></summary>
  81. The repo includes `.mcp.json` — detected automatically:
  82. ```bash
  83. cd civ6-mcp
  84. claude
  85. ```
  86. </details>
  87. <details>
  88. <summary><strong>Claude Desktop</strong></summary>
  89. Add to your config file:
  90. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  91. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  92. ```json
  93. {
  94. "mcpServers": {
  95. "civ6": {
  96. "command": "uv",
  97. "args": ["run", "--directory", "/path/to/civ6-mcp", "civ-mcp"]
  98. }
  99. }
  100. }
  101. ```
  102. </details>
  103. <details>
  104. <summary><strong>Codex</strong></summary>
  105. Add to `.codex/config.toml` in the project root:
  106. ```toml
  107. [mcp_servers.civ6]
  108. command = "uv"
  109. args = ["run", "--directory", "/path/to/civ6-mcp", "civ-mcp"]
  110. ```
  111. </details>
  112. <details>
  113. <summary><strong>Gemini CLI</strong></summary>
  114. Add to `.gemini/settings.json` in the project root:
  115. ```json
  116. {
  117. "mcpServers": {
  118. "civ6": {
  119. "command": "uv",
  120. "args": ["run", "--directory", "/path/to/civ6-mcp", "civ-mcp"]
  121. }
  122. }
  123. }
  124. ```
  125. </details>
  126. <details>
  127. <summary><strong>Other MCP clients</strong></summary>
  128. The server speaks stdio JSON-RPC:
  129. ```bash
  130. uv run civ-mcp
  131. ```
  132. </details>
  133. ### 5. Play
  134. Load a game in Civ 6, connect your client, and try:
  135. ```
  136. Play my Civ 6 game. Start by getting an overview, then check units and
  137. cities, and play through the turn.
  138. ```
  139. The agent will orient with `get_game_overview`, scan the map for threats, move units, set production and research, handle diplomacy, and end the turn.
  140. ## As a benchmark
  141. Civilization 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.
  142. - **Multi-turn planning** — decisions compound over hundreds of turns with delayed payoffs
  143. - **Incomplete information** — fog of war, hidden AI intentions, unexplored map
  144. - **Resource management** — balancing gold, production, science, culture, faith, and military
  145. - **Opponent modeling** — reading diplomatic signals, anticipating AI behavior
  146. - **Strategic adaptation** — responding to threats, shifting priorities mid-game
  147. The 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.
  148. ## How it works
  149. ```
  150. Claude / Any MCP Client
  151. | stdio (JSON-RPC)
  152. v
  153. MCP Server (Python) <- 70+ tools
  154. |
  155. | Generates Lua code at runtime
  156. | TCP :4318
  157. v
  158. Civilization VI <- Game is the TCP server
  159. ```
  160. The 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.
  161. The 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.
  162. ## Requirements
  163. - **macOS, Windows, or Linux** with Civilization VI (Steam version, Gathering Storm DLC)
  164. - **Python 3.12+** with [uv](https://docs.astral.sh/uv/)
  165. - An **MCP client** (Claude Code, Codex, Gemini CLI, or any MCP-compatible client)
  166. ## License
  167. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.