Skip to content
Back to search

eu4-save-mcp

MCP server: chat with your Europa Universalis IV save files in Claude (Windows/macOS/Linux, ironman via rakaly)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/adnan-kutay-yuksel--eu4-save-mcp/badge.svg)](/listings/adnan-kutay-yuksel--eu4-save-mcp)

HTML

<a href="/listings/adnan-kutay-yuksel--eu4-save-mcp"><img src="/api/listings/adnan-kutay-yuksel--eu4-save-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Desktop (one click)

1. Download `eu4-save-mcp.mcpb` from the [latest release](https://github.com/adnan-kutay-yuksel/eu4-save-mcp/releases/latest). 2. Double-click it (or drag it into Claude Desktop → Settings → Extensions) and press **Install**. 3. Optional settings: a custom save folder and the path to `rakaly` (for ironman saves).

Claude Code

claude mcp add eu4 -- npx -y github:adnan-kutay-yuksel/eu4-save-mcp

Any MCP client (JSON config)

{
  "mcpServers": {
    "eu4": {
      "command": "npx",
      "args": ["-y", "github:adnan-kutay-yuksel/eu4-save-mcp"],
      "env": { "EU4_SAVE_DIR": "", "RAKALY_PATH": "" }
    }
  }
}

Requires Node.js 18+ (Claude Desktop ships its own runtime for `.mcpb` extensions).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 121 lines
  1. # EU4 Save Advisor — MCP server for Europa Universalis IV
  2. Chat with your **Europa Universalis IV** campaign. This [Model Context Protocol](https://modelcontextprotocol.io) server lets Claude (Claude Desktop, Claude Code, or any MCP client) read your save files and give you grounded, strategic insights:
  3. > *"Why am I losing money?"* · *"Can I beat the Ottomans right now?"* · *"What should I fix first?"* · *"How far have I come since my 1600 save?"* · *"Who hates me the most?"*
  4. It works on **Windows, macOS and Linux**, auto-detects your save folders (local, OneDrive-redirected Documents, Steam Cloud, custom `userdir.txt`), reads your installed game version and language, and adapts to the save's own version, DLCs and mods. It is **read-only** — it never modifies your saves, and nothing leaves your computer except what you choose to send to Claude.
  5. ## What it can do
  6. | Tool | What you get |
  7. | --- | --- |
  8. | `eu4_environment` | OS, detected save folders, game install + version, language, rakaly status |
  9. | `eu4_list_saves` | Your saves, newest first, with in-game date, country, version, ironman flag |
  10. | `eu4_load_save` | Campaign summary: date, version, DLCs, mods, human players, player snapshot |
  11. | `eu4_country_overview` | Ruler/heir stats, government, tech, monarch points, ideas, treasury, loans, stability, manpower, army/navy, wars |
  12. | `eu4_economy` | Last month's income/expense breakdown (taxation, trade, army maintenance …) with %, lifetime spending, loans & interest |
  13. | `eu4_military` | Every army (infantry/cavalry/artillery, strength, morale, location), navies, traditions, and a comparison with rivals & enemies |
  14. | `eu4_diplomacy` | Allies, royal marriages, subjects + liberty desire, rivals and who rivals you, best/worst opinions |
  15. | `eu4_wars` | Active wars: sides, war goal, contribution, losses, recent battles |
  16. | `eu4_provinces` | Owned provinces: development, trade goods, culture/religion mismatch, cores, autonomy, devastation, buildings |
  17. | `eu4_find_problems` | **Health check** — deficits, loans, inflation, stability, overextension, wasted monarch points, empty idea slots, tech gaps, rebels, estates, succession… with concrete advice |
  18. | `eu4_rankings` | World ranking by development, income, manpower, army, treasury, tech, debt … |
  19. | `eu4_compare_countries` | Side-by-side comparison |
  20. | `eu4_trends` | Yearly income / size / score / inflation history from the game's ledger |
  21. | `eu4_compare_saves` | Your progress between two saves |
  22. | `eu4_query` / `eu4_search` | Raw access to any field in the save, for anything the reports don't cover |
  23. | `eu4_explain` | Short rules explanation + tips for core mechanics |
  24. There is also a `campaign_review` prompt that runs a full review in one go.
  25. ## Install
  26. ### Claude Desktop (one click)
  27. 1. Download `eu4-save-mcp.mcpb` from the [latest release](https://github.com/adnan-kutay-yuksel/eu4-save-mcp/releases/latest).
  28. 2. Double-click it (or drag it into Claude Desktop → Settings → Extensions) and press **Install**.
  29. 3. Optional settings: a custom save folder and the path to `rakaly` (for ironman saves).
  30. ### Claude Code
  31. ```bash
  32. claude mcp add eu4 -- npx -y github:adnan-kutay-yuksel/eu4-save-mcp
  33. ```
  34. ### Any MCP client (JSON config)
  35. ```json
  36. {
  37. "mcpServers": {
  38. "eu4": {
  39. "command": "npx",
  40. "args": ["-y", "github:adnan-kutay-yuksel/eu4-save-mcp"],
  41. "env": { "EU4_SAVE_DIR": "", "RAKALY_PATH": "" }
  42. }
  43. }
  44. }
  45. ```
  46. Requires Node.js 18+ (Claude Desktop ships its own runtime for `.mcpb` extensions).
  47. ## Save formats & ironman
  48. | Save type | Supported |
  49. | --- | --- |
  50. | Plaintext (`EU4txt`) | ✅ built in |
  51. | Compressed (zip) | ✅ built in (deflate & zstd) |
  52. | Ironman / binary (`EU4bin`) | ✅ with the free [rakaly CLI](https://github.com/rakaly/cli/releases) |
  53. Paradox's binary token table is not public, so binary saves are decoded by **rakaly**, an open-source tool by the pdx.tools author. Download the build for your OS (`aarch64-apple-darwin` for Apple Silicon Macs, `x86_64-apple-darwin` for Intel Macs, `x86_64-pc-windows-msvc` for Windows), extract it, and either put it on your `PATH` or point `RAKALY_PATH` at it. The server also looks in `~/Downloads/rakaly-*` automatically. Run `eu4_environment` to check. Tested with rakaly 0.8.25.
  54. Without the game installed, infantry/cavalry/artillery are estimated from unit names; when your EU4 install is found they come from the game files.
  55. ## Tested with real saves
  56. Besides synthetic unit tests, every release is checked against 12 real community saves from the public [pdx.tools](https://pdx.tools) test corpus: patches 1.29 to 1.35, plaintext, compressed, ironman/binary, multiplayer, modded, no-DLC and Random New World games, from 1444 starts to 1817 late games with 970+ provinces. To run that yourself:
  57. ```bash
  58. REAL_SAVES_DIR=/path/to/saves RAKALY_PATH=/path/to/rakaly npm test
  59. ```
  60. ## Where saves are found
  61. | OS | Default location |
  62. | --- | --- |
  63. | Windows | `%USERPROFILE%\Documents\Paradox Interactive\Europa Universalis IV\save games` (also OneDrive\Documents) |
  64. | macOS | `~/Documents/Paradox Interactive/Europa Universalis IV/save games` |
  65. | Linux | `~/.local/share/Paradox Interactive/Europa Universalis IV/save games` |
  66. | Steam Cloud | `<Steam>/userdata/<id>/236850/remote/save games` |
  67. Overrides (environment variables): `EU4_SAVE_DIR` (one or more folders, separated by `;` on Windows / `:` elsewhere), `EU4_USER_DIR`, `EU4_GAME_DIR`, `RAKALY_PATH`.
  68. When the game install is found, country/province names come from your installed localisation (matching your in-game language and mods); otherwise a built-in list of common tags is used.
  69. ## Example conversation
  70. > **You:** Load my latest save and tell me what's wrong.
  71. >
  72. > **Claude:** *(calls `eu4_load_save`, `eu4_find_problems`)* It's 1550 and France is the #1 development power, but: you're running a −1.5 ducat/month deficit with two 200-ducat loans, stability is 0 while war exhaustion is 6.5, the Clergy is at 85% influence (disaster at 100%), and your ADM is sitting at 950/999 — spend it on coring Lorraine, which also brings overextension down from 60%…
  73. ## Development
  74. ```bash
  75. npm install
  76. npm run typecheck
  77. npm test # parser, analysis and stdio MCP integration tests
  78. npm run build # bundles to dist/index.js (committed, so `npx github:` works without a build)
  79. npm run pack # builds eu4-save-mcp.mcpb for Claude Desktop
  80. ```
  81. The parser (`src/core/clausewitz.ts`) is a dependency-free byte-level Clausewitz parser that skips heavy sections (province history, trade nodes, flags) by default; a ~40 MB save loads in about 0.4 s.
  82. ## Related projects
  83. - [EU5 Save Advisor](https://github.com/adnan-kutay-yuksel/eu5-save-mcp) — the same for Europa Universalis V
  84. - [GTA 6 Guide MCP](https://github.com/adnan-kutay-yuksel/gta6-mcp) — knowledge-base companion for Grand Theft Auto VI
  85. - [pdx.tools](https://pdx.tools) and [rakaly](https://github.com/rakaly) — the excellent open-source Paradox save tooling this project relies on for binary saves
  86. ## License
  87. MIT. Not affiliated with or endorsed by Paradox Interactive. Europa Universalis is a trademark of Paradox Interactive AB.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.