Civ5 MCP

🚀 Civ 5 MCP

Connect your Civilization 5 game to an agent using the Mod Communication Protocol (MCP). This mod establishes an Inter-Process Communication (IPC) channel from your real - time game to an MCP server, enabling interaction with your agent.

See some samples.

The core concept of this mod is to provide access only to information that a human player could reasonably know. For example, we avoid revealing the locations of wonders or unmet players. The goal is to create a super - advisor to help you improve your game performance.

The project consists of two components: the game mod (the Bridge) and the MCP server. Both are required to use this mod.

⚠️ Important Note

This mod has only been tested on the Brave New World expansion of Civilization 5 on Windows.

🚀 Quick Start

Steps to Try the Mod

1. Download the latest release and extract its contents to your MODS directory. Typically, it is located at %USERPROFILE%\Documents\My Games\Sid Meier's Civilization 5\MODS.
   • The directory structure should look like this:

MODS/
  Civ5MCP_Bridge (v VERSION)/
      Civ5MCP_Bridge.modinfo
      ... a bunch of .lua files ...

2. Launch your game.
3. Select the "MODS" option.
4. Check the checkbox to enable this mod.
5. Configure your game settings.
6. Configure your agent to run server/civ5_mcp_server.py.
7. Enjoy the game!

💻 Development

🛠️ Build

The modinfo and constants file are generated during the build process. mod_config.json describes the mod and the files that will be exported in the format expected by Civilization 5.

# All targets have a docker- variant, e.g. make docker-lint

# Get nagged
make lint

# Run unit tests
make test

# Produces a directory that Civ 5 can read
make build

# Optional: automatically deploy to your Civ 5 MODS folder
./tools/deploy.ps1

🔢 Versioning

The Lua rockspec and Civilization 5 version formats differ. Civilization 5 requires a string without dots or dashes. Therefore, the Civilization 5 version strips off the revision and combines the major and minor versions into major * 10 + minor.

🌉 Bridge

The game state is recorded at the start of each turn and stored in a SQLite database. Each new game is saved as a new session. The session and turn number serve as the state's identifier. Turn history and the initial game configuration are stored using this session ID.

⚠️ Important Note

The data field is a JSON blob and its format is considered unstable!

The bridge operates in a Lua 5.1.4 sandbox with a very limited API. The game exposes this API, which is the main resource we can utilize.

🖥️ Running the Server

cd server

# Test that the server can be launched
uv run civ5_mcp_server.py

If no errors occur, you can add this server to an application like Claude using a configuration similar to the following. If uv fails to launch, try using uv's virtual environment Python binary directly.

{
  "mcpServers": {
    "civ5": {
      "command": "uv",
      "args": ["run", "path/to/civ5_mcp_server.py"],
    }
  }
}