Skip to content

About

A Stellaris MCP interface that allow AI like claude code or opencode play the videogame Stellaris. MCP server that enables AI like Claude or Opencode to read game state and send commands to Stellaris via save file parsing, real-time log monitoring, and a companion PDXScript mod.

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

Stellaris MCP Server

MCP (Model Context Protocol) server that allows an AI to read game state and send commands to Stellaris (Paradox Interactive). Designed for Stellaris Cetus V4.3.1.

Architecture

The system has three components:

┌─────────────────┐      game.log       ┌─────────────────┐     stdio      ┌─────────────┐
│  Stellaris Mod   │ ──────────────────► │   MCP Server    │ ◄────────────► │  AI (Claude) │
│  (PDXScript)     │                     │   (TypeScript)  │                │              │
│                  │ ◄────────────────── │                 │                │              │
│                  │   ai_commands.txt   │                 │                │              │
└─────────────────┘                     └────────┬────────┘                └──────────────┘
                                                 │
                                                 │ parse .sav
                                                 ▼
                                        ┌─────────────────┐
                                        │   Save Files     │
                                        │   (.sav / ZIP)   │
                                        └─────────────────┘
  1. Stellaris Mod (mod/) — PDXScript mod that hooks into on_monthly_pulse_country and dumps structured game state to game.log every in-game month.
  2. Save File Parser (src/parser/) — Uses the jomini npm package to parse .sav files (ZIP archives containing Clausewitz-format text).
  3. MCP Server (src/index.ts) — stdio-transport MCP server exposing tools for the AI to read state and queue commands.

Key Constraint

The Clausewitz engine has no external API — no REST, no WebSocket, no IPC. The mod can only write to game.log (one-way observation). Commands go through ai_commands.txt, which the player executes in the console via run ai_commands.txt.

MCP Tools

Tool Description
get_game_state Complete game state from the latest save or real-time log
get_resources Resource stockpiles and monthly income (13 resource types)
get_planets Owned planets with pops, stability, buildings, districts, crime, jobs
get_fleets Fleet composition, military power, location
get_technologies Active research and completed tech list
get_diplomacy Relations with all known empires (opinion, rivalries, pacts, wars)
execute_command Queue a single console command
execute_effect Queue a PDXScript effect command
queue_commands Queue multiple console commands at once
list_save_profiles List available save game profiles
analyze_situation Comprehensive strategic analysis combining all data sources

Mod Data Export

The mod writes to game.log every month with pipe-delimited lines:

Prefix Data
AI_SUMMARY Date, empire name, planets, pops, navy used/cap, military power
AI_RESOURCES Per-resource stockpile and monthly income
AI_PLANET Per-planet: name, class, pops, size, stability, amenities, housing, jobs, crime
AI_FLEET Per-fleet: name, ships, power, MIA status
AI_DIPLO Per-empire: name, opinion, rival/pact/war status
AI_TECH_OUTPUT Physics/society/engineering research output
AI_STATE_END End-of-dump marker

Setup

Prerequisites

  • Node.js 18+
  • Stellaris (non-ironman for console commands; save parsing works with ironman too)

Install

# Clone and install dependencies
git clone <repo-url>
cd stellaris-mcp
npm install

# Build
npm run build

Install the Stellaris Mod

bash scripts/install-mod.sh

Or manually copy the mod/ contents to:

Documents/Paradox Interactive/Stellaris/mod/ai_player_mcp/

And create Documents/Paradox Interactive/Stellaris/mod/ai_player_mcp.mod:

name="AI Player MCP Bridge"
path="mod/ai_player_mcp"
tags={
    "Utilities"
}
supported_version="4.3.*"

Then activate "AI Player MCP Bridge" in the Stellaris launcher under Mods.

Configure the MCP Server

Add to your Claude Code or Claude Desktop MCP settings:

{
  "mcpServers": {
    "stellaris": {
      "command": "node",
      "args": ["<path-to-project>/dist/index.js"],
      "env": {
        "STELLARIS_SAVE_PROFILE": "ia"
      }
    }
  }
}

Environment Variables

Variable Default Description
STELLARIS_DOCUMENTS_PATH ~/Documents/Paradox Interactive/Stellaris Stellaris user data directory
STELLARIS_INSTALL_PATH F:/SteamLibrary/steamapps/common/Stellaris Game installation directory
STELLARIS_SAVE_PROFILE (empty) Save game profile folder name

Usage

Reading Game State

The AI can call any read tool at any time. Data sources:

  • Save file parsing — full game state from the latest .sav file
  • Log monitoring — real-time updates from the mod's game.log output (requires mod to be active)

Sending Commands

  1. The AI queues commands via execute_command, execute_effect, or queue_commands
  2. Commands are written to Documents/Paradox Interactive/Stellaris/ai_commands.txt
  3. In-game, open the console (~) and type: run ai_commands.txt

Example commands the AI might generate:

# Direct console commands
cash 1000
research_technology tech_lasers_2
influence 100

# Effect commands (wrapped automatically)
effect add_resource = { energy = 500 }
effect every_owned_planet = { limit = { free_jobs > 5 } add_building = building_factory_1 }

Testing the Parser

# Parse all save profiles and print results
npm run test:parser

Project Structure

stellaris-mcp/
├── mod/                                  # Stellaris mod (PDXScript)
│   ├── descriptor.mod
│   ├── common/
│   │   ├── on_actions/                   # Monthly pulse hooks
│   │   └── scripted_effects/             # State dump effects
│   ├── events/                           # ai_player event chain
│   └── localisation/english/
├── src/                                  # MCP Server (TypeScript)
│   ├── index.ts                          # Server entry point + tool definitions
│   ├── config.ts                         # Configuration loading
│   ├── parser/
│   │   ├── types.ts                      # Game state TypeScript interfaces
│   │   ├── save-parser.ts                # .sav file parser (jomini)
│   │   ├── log-parser.ts                 # game.log parser
│   │   └── test-parser.ts               # Parser test script
│   ├── tools/
│   │   └── get-game-state.ts             # State formatting for MCP responses
│   ├── watcher/
│   │   ├── save-watcher.ts               # Autosave directory watcher
│   │   └── log-watcher.ts                # game.log tail watcher
│   └── commands/
│       └── command-writer.ts             # Console command file writer
├── scripts/
│   └── install-mod.sh                    # Mod installer script
├── package.json
└── tsconfig.json

Limitations

  • No real-time command injection — the Clausewitz engine cannot receive commands from external programs. Commands require manual console execution.
  • Localization keys — save files store internal keys (e.g. %ADJECTIVE%, NEW_COLONY_NAME_1) rather than display names. The game resolves these at runtime.
  • Monthly log frequency — the mod dumps state once per in-game month. For more frequent updates, use save file parsing with shorter autosave intervals.
  • Non-ironman required — console commands and the run command only work in non-ironman games. Save parsing works with both modes.

Future Plans

  • Phase 2: Command injection via save file flags — modify save files to set global flags that the mod reads and executes as actions, enabling a fully autonomous loop.
  • Phase 3: Hot-reload automation — use -debug_mode launch flag + console automation to inject and execute commands without manual interaction.

About

A Stellaris MCP interface that allow AI like claude code or opencode play the videogame Stellaris. MCP server that enables AI like Claude or Opencode to read game state and send commands to Stellaris via save file parsing, real-time log monitoring, and a companion PDXScript mod.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages