Aurora 4x MCP Server

A read-only MCP (Model Context Protocol) server that lets Claude query your Aurora 4x campaign database directly. Claude can look up colonies, fleets, minerals, commanders, ordnance, and more. It can register, edit, and promote new queries against your live DB without restarting. You can have natural language conversations with the LLM about your game state, ask for reports, and do analysis across the board.

AI/LLM DISCLAIMER: This tool was generated with the assistance of claude code by a user who has a solid grasp on the game. This tool is built specificially to query the DB, and nothing else. If you write to the DB you may cause unintended consquence and will not be able to receive support by the larger community.

Getting started

Once the server is connected, start a new Claude Code session and say:

Please verify my current game and give me a description of the available tools.

Claude will call get_session_context to confirm the right campaign is loaded, let you know that query results are limited to 200 rows by default, and ask whether you'd like to disable that limit for the session. It will then summarize what each tool does. From there you can ask natural-language questions about your empire — minerals, colonies, fleets, commanders, ordnance — and Claude will pick the right tools automatically.

Prerequisites

• Python 3.10 or later

• Aurora 4x installed with at least one active campaign saved

• Claude Code or Claude Desktop

Installation

1. Place the server files

Copy the server directory somewhere permanent. These docs assume:

D:\Aurora\aurora-mcp\
  server.py
  queries.json
  pyproject.toml

Adjust all paths below if you use a different location.

2. Install the Python dependency

Open a terminal and run:

pip install "mcp>=1.0.0"

Or install from the project directory using the included pyproject.toml:

cd D:\Aurora\aurora-mcp
pip install -e .

3. Locate your Aurora database

Aurora 4x always stores its database in its own install folder. The file you need is AuroraDB.db, sitting directly inside the Aurora directory — the same folder that contains Aurora.exe.

D:\Aurora\AuroraDB.db    ← example; your install path may differ

You must set AURORA_DB_PATH to this file's full path in the config below. There is no default that will work out of the box.

4. Connect to Claude Desktop / Claude Code

Edit the MCP configuration file:

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

If the file doesn't exist yet, create it. Add the following, replacing the paths with your actual paths:

{
  "mcpServers": {
    "aurora4x": {
      "command": "python",
      "args": [
        "D:/Aurora/aurora-mcp/server.py"
      ],
      "env": {
        "AURORA_DB_PATH": "D:/Aurora/AuroraDB.db"
      }
    }
  }
}

Path format: Use forward slashes (/) even on Windows, or double backslashes (\\). Single backslashes will cause a JSON parse error.

If you already have other MCP servers in your config, add the "aurora4x" block inside the existing "mcpServers" object — don't create a second one.

5. Restart and verify

Close and reopen Claude Desktop / Claude Code. In a new session, ask:

Call get_session_context to confirm the right campaign is loaded.

Claude should return your GameID, GameName, RaceID, and RaceName. If it does, you're good to go.

Environment variables

Available tools

Ad-hoc query

Introspection

Query registry

Jump network

Registered queries

Queries are stored in queries.json and loaded on every request — no restart needed after changes. All registered queries also accept limit_query: false to bypass the 200-row cap.

Empire

Alien intelligence

These queries expose information about other races and may reveal spoilers. SPOILER_GUARD_other_races should be called first to confirm the player wants to proceed.

Row limits

All query tools cap results at 200 rows by default. This is a fixed limit — it cannot be changed in config. When results are truncated, the response will include a notice.

To retrieve the full result set, pass limit_query: false on any tool call. This bypasses the cap entirely and may return a large number of rows, consuming significantly more tokens.

Query lifecycle

The server reloads queries.json on every request, so all registry changes take effect immediately.

execute_sql          ← explore with ad-hoc SQL
    ↓
register_query       ← save a promising query as DRAFT_<name>
    ↓
update_query         ← fix SQL or params as needed
    ↓
promote_query        ← once verified, strip DRAFT_ and mark verified=true
    ↓
delete_query         ← remove broken or superseded drafts

Important: save before querying

Troubleshooting

Server doesn't appear in Claude Code

• Confirm python resolves in your PATH: run python --version in a terminal.

• Confirm the path to server.py in args is correct and uses forward slashes or \\.

• Check Claude Code's MCP logs (Developer → MCP Servers) for startup errors.

"No active campaign found"

• The server finds the campaign via MAX(GameID) WHERE GameName != 'Sample'. Make sure you have a real saved game, not just the built-in sample campaign.

"No player race found"

• The server looks for MIN(RaceID) with NPR = 0. If that doesn't match your setup, inspect FCT_Race with describe_table and execute_sql.

Wrong campaign loaded

• The server picks the highest GameID. If you have multiple campaigns, the most recently created one wins. Verify with get_session_context.

A DRAFT query returns wrong column names

• Use describe_table on the relevant table to check exact column names, then fix the query with update_query.