EU5 Save Advisor
# EU5 Save Advisor — MCP server for Europa Universalis V
Chat with your **Europa Universalis V** campaign. This [Model Context Protocol](https://modelcontextprotocol.io) server lets Claude (Claude Desktop, Claude Code, or any MCP client) read your save files and answer questions with real numbers from your game:
> *"Why is my gold going down?"* · *"Which of my locations have the worst control?"* · *"How do I compare to the other great powers?"* · *"What changed since my last save?"* · *"How does control actually work?"*
It is **read-only**, runs locally, and adapts to your platform and game version.
## Platform support
EU5 is a Windows game. The server knows where saves end up on every setup:
| Setup | Save folder searched automatically |
| --- | --- |
| Windows | `%USERPROFILE%\Documents\Paradox Interactive\Europa Universalis V\save games` (+ OneDrive\Documents) |
| Linux (Steam Proton) | `<Steam library>/steamapps/compatdata/3450310/pfx/drive_c/users/steamuser/Documents/Paradox Interactive/Europa Universalis V/save games` |
| macOS via CrossOver / Whisky | `drive_c/users/<user>/Documents/Paradox Interactive/Europa Universalis V/save games` inside every bottle |
| Steam Cloud copy | `<Steam>/userdata/<id>/3450310/remote/save games` |
| Cloud streaming / VM | copy the `.eu5` file to your computer and pass its path, or set `EU5_SAVE_DIR` |
Run `eu5_environment` to see exactly what was detected (OS, folders, game install + version, language, rakaly).
## Save formats
| Save type | How it is read |
| --- | --- |
| **Debug-mode saves** (plaintext) | ✅ built in — start EU5 with the launch option `-debug_mode` (Steam → Properties → Launch Options). Note: debug mode disables achievements. |
| Normal & ironman saves (binary, zipped) | ✅ via the free [rakaly CLI](https://github.com/rakaly/cli/releases) if your rakaly build supports EU5 |
Paradox's binary format uses a token table that is not public; [rakaly](https://github.com/rakaly) (the engine behind [pdx.tools](https://pdx.tools)) decodes it. Download the build for your OS, extract it, and put it on your `PATH` or point `RAKALY_PATH` at it (the server also looks in `~/Downloads/rakaly-*`). If your rakaly version cannot read a brand-new EU5 patch yet, you'll get a clear message — update rakaly or use a debug-mode save.
## Tools
| Tool | What you get |
| --- | --- |
| `eu5_environment` | OS, platform notes, save folders, game install/version, language, rakaly status |
| `eu5_list_saves` | Saves newest first with date, country, version, format |
| `eu5_load_save` | Campaign summary + player snapshot |
| `eu5_country_overview` | Gold, manpower, stability, prestige, traditions, income/expense, tax & trade, great-power rank, territory, rulers, wars — plus every other scalar field of your country |
| `eu5_economy` | All economic fields, loans, and the locations with the most untapped tax |
| `eu5_locations` | Development, control, prosperity, tax vs possible tax, market access, raw materials, ranks, occupation |
| `eu5_diplomacy` | Overlord, subjects with liberty desire, your diplomacy record, wars |
| `eu5_wars` | Wars with sides and battles |
| `eu5_find_problems` | Health check: deficit, debt, stability, prestige, manpower, control, untapped tax, market access, occupation, multi-front wars |
| `eu5_rankings` | Great-power rank, gold, income, manpower, prestige, stability, locations, score, tax base |
| `eu5_compare_saves` | Your progress between two saves |
| `eu5_country_raw` / `eu5_query` / `eu5_search` | Raw access to any part of the save — EU5's schema changes between patches, so nothing is out of reach |
| `eu5_wiki_search` / `eu5_wiki_page` | The official [EU5 wiki](https://eu5.paradoxwikis.com) for rules and mechanics |
There is also a `campaign_review` prompt.
## Install
### Claude Desktop (one click)
1. Download `eu5-save-mcp.mcpb` from the [latest release](https://github.com/adnan-kutay-yuksel/eu5-save-mcp/releases/latest).
2. Double-click it (or drag it into Claude Desktop → Settings → Extensions) and press **Install**.
3. Optional: set your save folder and the path to `rakaly`.
### Claude Code
```bash
claude mcp add eu5 -- npx -y github:adnan-kutay-yuksel/eu5-save-mcp
```
### Any MCP client
```json
{
"mcpServers": {
"eu5": {
"command": "npx",
"args": ["-y", "github:adnan-kutay-yuksel/eu5-save-mcp"],
"env": { "EU5_SAVE_DIR": "", "RAKALY_PATH": "" }
}
}
}
```
Environment overrides: `EU5_SAVE_DIR` (one or more folders), `EU5_USER_DIR`, `EU5_GAME_DIR`, `RAKALY_PATH`. Requires Node.js 18+ (Claude Desktop bundles its own for `.mcpb`).
## How it reads the save
An EU5 save starts with a one-line header (`SAV02…`) that says whether it is a debug (text) or packed (binary) save. Text saves are parsed by a fast, dependency-free Clausewitz parser; packed saves are a ZIP (`gamestate` + `string_lookup`) that rakaly melts to text first. Country, location and character data are interpreted using the field names of the open-source `eu5save` models from [rakaly/jomini](https://github.com/rakaly/jomini); location names come from the save's own location list and, when the game is installed, from your localisation files.
## Development
```bash
npm install
npm run typecheck
npm test # parser, analysis and stdio MCP integration tests
npm run build # bundles to dist/index.js (committed so `npx github:` works)
npm run pack # builds eu5-save-mcp.mcpb
```
## Related
- [EU4 Save Advisor](https://github.com/adnan-kutay-yuksel/eu4-save-mcp)
- [GTA 6 Guide MCP](https://github.com/adnan-kutay-yuksel/gta6-mcp)
## License
MIT. Not affiliated with or endorsed by Paradox Interactive. Europa Universalis is a trademark of Paradox Interactive AB.
TDQS
Scored across 16 tools
The domain tools (country_overview, economy, locations, diplomacy, wars) target distinct facets of a save and have descriptions that clarify boundaries. The only real overlap is among the generic introspection trio (country_raw, query, search) and their relation to country_overview, where an agent may hesitate between a raw dump, a dotted-path read, and a regex search.
All 16 tools share a uniform eu5_ prefix and snake_case, which is highly predictable. Minor inconsistency: action tools use verb_noun (list_saves, load_save, find_problems, compare_saves, wiki_search) while analysis tools are bare nouns (economy, locations, wars).
Sixteen tools is at the upper edge of ideal but each maps to a recognizable analysis task (environment, discovery, reporting, comparison, introspection, wiki lookup). Nothing looks like filler, though the retrieval layer plus the wiki layer together push it slightly past the comfortable range.
The surface covers the full read-only lifecycle: detect environment, list saves, load, then analyze country/economy/locations/diplomacy/wars, rank, compare saves, and consult wiki. Gaps are secondary domains such as military/army detail, technology, and buildings, but the generic query/search/raw tools provide an escape hatch for uncovered fields.