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.
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) │
└─────────────────┘
- Stellaris Mod (
mod/) — PDXScript mod that hooks intoon_monthly_pulse_countryand dumps structured game state togame.logevery in-game month. - Save File Parser (
src/parser/) — Uses the jomini npm package to parse.savfiles (ZIP archives containing Clausewitz-format text). - MCP Server (
src/index.ts) — stdio-transport MCP server exposing tools for the AI to read state and queue commands.
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.
| 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 |
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 |
- Node.js 18+
- Stellaris (non-ironman for console commands; save parsing works with ironman too)
# Clone and install dependencies
git clone <repo-url>
cd stellaris-mcp
npm install
# Build
npm run buildbash scripts/install-mod.shOr 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.
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"
}
}
}
}| 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 |
The AI can call any read tool at any time. Data sources:
- Save file parsing — full game state from the latest
.savfile - Log monitoring — real-time updates from the mod's
game.logoutput (requires mod to be active)
- The AI queues commands via
execute_command,execute_effect, orqueue_commands - Commands are written to
Documents/Paradox Interactive/Stellaris/ai_commands.txt - 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 }
# Parse all save profiles and print results
npm run test:parserstellaris-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
- 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
runcommand only work in non-ironman games. Save parsing works with both modes.
- 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_modelaunch flag + console automation to inject and execute commands without manual interaction.