Skip to main content
Glama

EU4 Save Advisor — MCP server for Europa Universalis IV

Chat with your Europa Universalis IV campaign. This Model Context Protocol server lets Claude (Claude Desktop, Claude Code, or any MCP client) read your save files and give you grounded, strategic insights:

"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?"

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.

What it can do

Tool

What you get

eu4_environment

OS, detected save folders, game install + version, language, rakaly status

eu4_list_saves

Your saves, newest first, with in-game date, country, version, ironman flag

eu4_load_save

Campaign summary: date, version, DLCs, mods, human players, player snapshot

eu4_country_overview

Ruler/heir stats, government, tech, monarch points, ideas, treasury, loans, stability, manpower, army/navy, wars

eu4_economy

Last month's income/expense breakdown (taxation, trade, army maintenance …) with %, lifetime spending, loans & interest

eu4_military

Every army (infantry/cavalry/artillery, strength, morale, location), navies, traditions, and a comparison with rivals & enemies

eu4_diplomacy

Allies, royal marriages, subjects + liberty desire, rivals and who rivals you, best/worst opinions

eu4_wars

Active wars: sides, war goal, contribution, losses, recent battles

eu4_provinces

Owned provinces: development, trade goods, culture/religion mismatch, cores, autonomy, devastation, buildings

eu4_find_problems

Health check — deficits, loans, inflation, stability, overextension, wasted monarch points, empty idea slots, tech gaps, rebels, estates, succession… with concrete advice

eu4_rankings

World ranking by development, income, manpower, army, treasury, tech, debt …

eu4_compare_countries

Side-by-side comparison

eu4_trends

Yearly income / size / score / inflation history from the game's ledger

eu4_compare_saves

Your progress between two saves

eu4_query / eu4_search

Raw access to any field in the save, for anything the reports don't cover

eu4_explain

Short rules explanation + tips for core mechanics

There is also a campaign_review prompt that runs a full review in one go.

Related MCP server: vic3-mcp

Install

Claude Desktop (one click)

  1. Download eu4-save-mcp.mcpb from the latest release.

  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).

Save formats & ironman

Save type

Supported

Plaintext (EU4txt)

✅ built in

Compressed (zip)

✅ built in (deflate & zstd)

Ironman / binary (EU4bin)

✅ with the free rakaly CLI

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.

Where saves are found

OS

Default location

Windows

%USERPROFILE%\Documents\Paradox Interactive\Europa Universalis IV\save games (also OneDrive\Documents)

macOS

~/Documents/Paradox Interactive/Europa Universalis IV/save games

Linux

~/.local/share/Paradox Interactive/Europa Universalis IV/save games

Steam Cloud

<Steam>/userdata/<id>/236850/remote/save games

Overrides (environment variables): EU4_SAVE_DIR (one or more folders, separated by ; on Windows / : elsewhere), EU4_USER_DIR, EU4_GAME_DIR, RAKALY_PATH.

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.

Example conversation

You: Load my latest save and tell me what's wrong.

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%…

Development

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 without a build)
npm run pack      # builds eu4-save-mcp.mcpb for Claude Desktop

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.

  • EU5 Save Advisor — the same for Europa Universalis V

  • GTA 6 Guide MCP — knowledge-base companion for Grand Theft Auto VI

  • pdx.tools and rakaly — the excellent open-source Paradox save tooling this project relies on for binary saves

License

MIT. Not affiliated with or endorsed by Paradox Interactive. Europa Universalis is a trademark of Paradox Interactive AB.

Available Tools

17 tools
eu4_compare_countriesCompare countriesC

Side-by-side comparison of several countries (development, economy, tech, manpower, army, navy, stability…).

Inputs: tags (required), save.

eu4_compare_savesProgress between two savesA

Compare a country between an older and a newer save of the same campaign (development, provinces, income, debt, tech, army, rank…).

Inputs: older (required), tag, newer.

eu4_country_overviewCountry overviewB

Headline state of a country: ruler/heir stats, government, tech, monarch points, ideas, treasury & balance, loans, stability, prestige, war exhaustion, overextension, manpower, army/navy size, subjects and wars.

Inputs: tag, save.

eu4_diplomacyDiplomacy reportA

Alliances, royal marriages, subjects (with liberty desire), overlord, guarantees, rivals and who rivals you, active wars, and the best/worst opinions toward the player's country.

Inputs: tag, save.

eu4_economyEconomy reportB

Last month's income/expense breakdown (taxation, production, trade, army maintenance …) with percentages, last year totals, lifetime spending, loans with interest, inflation and corruption.

Inputs: tag, save.

eu4_environmentDetect EU4 setupA

Detect OS, EU4 user/save folders, game install + version, language, and whether the rakaly CLI (needed for ironman saves) is available. Call this first if saves can't be found.

Inputs: no named parameters.

eu4_explainExplain a mechanicA

Short explanation + tips for an EU4 mechanic (overextension, aggressive expansion, stability, war exhaustion, inflation, corruption, monarch points, ideas, development, trade, institutions, manpower, autonomy, estates, loans) with a wiki link.

Inputs: topic (required).

eu4_find_problemsCampaign health checkA

Scan a country for problems and missed opportunities (deficits, loans, inflation, low stability, overextension, wasted monarch points, empty idea slots, tech gaps, low manpower, rebels, estates, succession…) with concrete advice, sorted by severity.

Inputs: tag, save.

eu4_list_savesList EU4 savesB

List EU4 save files (newest first) with date, player country, version, ironman flag and size.

Inputs: dir, limit.

eu4_load_saveLoad an EU4 saveA

Parse a save (text, compressed, or ironman via rakaly) and return a campaign summary: date, player, version, DLCs, mods and the player's headline stats. Later tools reuse this save by default.

Inputs: full, save.

eu4_militaryMilitary reportC

Armies (regiments by infantry/cavalry/artillery, strength, morale, location), navies, manpower, traditions, professionalism, and a strength comparison against rivals and current enemies.

Inputs: tag, save.

eu4_provincesProvince reportC

Owned provinces with development, trade goods, culture/religion mismatches, cores, autonomy, devastation, buildings, occupation. Also lists uncored provinces and trade-good totals.

Inputs: tag, save, sort, limit.

eu4_queryRaw save lookupA

Read any raw field by dotted path, e.g. 'countries.FRA.technology', 'provinces.-183', 'diplomacy', 'great_powers'. Returns a depth-limited preview. Use eu4_search to discover paths.

Inputs: path, save, depth.

eu4_rankingsWorld rankingsC

Rank all living countries by a metric and show where the player stands.

Inputs: save, limit, metric.

eu4_warsActive warsA

All active wars (or only those involving a country): sides, war goal, participants' contribution and losses, recent battles.

Inputs: tag, save.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 17 tools

    Disambiguation4/5

    Each tool is anchored to a distinct facet: overview, economy, military, diplomacy, wars, provinces, with separate comparison, ranking, and problem-scanning tools. The only real soft spots are eu4_query vs eu4_search (read-by-path vs regex discovery), which partially overlap, and the boundary between eu4_country_overview and the per-facet tools, though descriptions clarify that the latter go deeper. An agent can pick the right tool in nearly all cases.

    Naming Consistency5/5

    Every tool uses the same eu4_ prefix with snake_case verb or noun phrasing (eu4_list_saves, eu4_load_save, eu4_find_problems, eu4_compare_countries). No style mixing, and the noun-based tools like eu4_economy/eu4_military are uniform among themselves.

    Tool Count4/5

    17 tools is at the upper end but each maps to a real analysis facet of an EU4 save (discovery, loading, five stat domains, comparisons, raw access, explainer), so little feels redundant. Slightly heavy, but justified by the breadth of the domain rather than padding.

    Completeness4/5

    The surface covers discovery, environment checks, save loading, core country domains, cross-save and cross-country comparison, plus an escape hatch (eu4_query/eu4_search) for anything not covered. Minor gaps exist around granular domains like religion, culture, estates detail, missions/decisions, or trade-node level data, and there is no export/report output, but agents can work around these via raw queries.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables Claude to read Crusader Kings III save files and retrieve strategic game information such as realm overview, military, succession, diplomacy, vassals, factions, and expansion options.
      14
      11
      4
      MIT
    • F
      license
      C
      quality
      C
      maintenance
      Enables AI agents to read local Victoria 3 save files, list saves, and analyze country, economy, politics, diplomacy, military, and technology data, while generating construction, law, and diplomatic advice.
      19
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables natural-language-driven generation and maintenance of Hearts of Iron IV mod content—including national focus trees, events, decisions, ideas, unit variants, localisation, and art prompts—with integrated lint validation and MCP integration for Claude Desktop, Cursor, and Windsurf.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets users interrogate an Europa Universalis V save with an AI assistant, returning real figures decoded from their own save, game files and wiki-verified rules for economy, locations, buildings, markets, diplomacy and strategy. It is read-only and reports unverifiable values as missing rather than guessing.
      AGPL 3.0