Local tooling for AI-assisted Hearts of Iron IV mod development.
HOI4-MCP is a local Model Context Protocol server and agent toolkit for Hearts of Iron IV modding.
It gives an MCP-capable coding assistant structured access to a mod, a locally indexed copy of vanilla game data, Clausewitz validation, parsed game errors, and project-specific rules learned from earlier corrections. The purpose is straightforward: make the assistant verify what it is doing instead of guessing.
This repository includes:
- an MCP server written in Python;
- a Clausewitz tokenizer, parser, and validator;
- a searchable SQLite index of vanilla HOI4 data;
- mod indexing and ID collision checks;
- structured
error.logparsing; - reusable HOI4 agent instructions, skills, and audit checklists;
- a persistent rule database for corrections and project conventions.
The server currently exposes 19 tools and 2 MCP resources. The tool count is verified by CI — see tests/test_tool_counts.py.
I built HOI4-MCP around a recurring problem: coding assistants can write a convincing block of Clausewitz script while still getting one identifier, scope, localisation key, or bracket wrong.
Those failures are rarely interesting. They usually come from missing context, invented vanilla IDs, incomplete searches, or the assistant forgetting a correction from an earlier session. The useful part of an assistant is not how confidently it writes code. It is whether it can inspect the project, check the game data, validate its work, and retain the rules that matter to the mod.
HOI4-MCP is an attempt to make that workflow practical. It does not replace in-game testing, design judgment, or familiarity with HOI4. It handles the repetitive verification work so more time can go into the mod itself.
get_mod_index builds a structured map of the active mod, including namespaces, events, focuses, decisions, ideas, characters, scripted effects, scripted triggers, on-actions, localisation keys, and other indexed systems.
The index can be returned as a summary, filtered by category, or refreshed after edits. This is considerably more reliable than asking an assistant to infer the structure of a large mod from a few open files.
lookup_vanilla queries a local SQLite database built from the installed copy of Hearts of Iron IV.
The database can be used to verify exact IDs and inspect vanilla focuses, events, decisions, ideas, characters, technologies, countries, and modifiers. This reduces avoidable mistakes such as citing a plausible but nonexistent vanilla focus or modifier.
validate_syntax checks Clausewitz script and HOI4 localisation before the game is launched.
Current validation covers bracket matching, malformed assignments, byte-order marks, localisation headers, and several common HOI4-specific mistakes. It is intended as a fast preflight check, not a substitute for the game parser.
get_latest_errors locates and parses the HOI4 error.log, groups errors into structured categories, and can identify recurring patterns.
This makes it possible for an assistant to work from the actual game output without requiring the user to repeatedly copy raw log fragments into the conversation.
The learning system stores corrections in a local SQLite database. Rules can describe syntax constraints, design conventions, scope requirements, localisation practices, performance concerns, or mod-specific decisions.
Rules can be queried before work begins, resolved when they become obsolete, exported as line-oriented JSON for version control, and imported on another machine.
The repository also includes HOI4-specific agent instructions, domain skills, audit checklists, and a guarded fuzzy editing tool for modifying files when exact text matching is unreliable.
These components are optional. The MCP server can still be used independently with any compatible client.
AI coding assistant
|
| Model Context Protocol
v
HOI4-MCP server
|
+-- Mod index and search
+-- Clausewitz and localisation validation
+-- Vanilla SQLite database
+-- Error log parser
+-- Learned rules database
+-- Skill and agent instruction library
|
v
HOI4 mod workspace and local game installation
All project data remains local unless the connected assistant or editor sends tool output elsewhere as part of its normal operation.
Tool count verified by CI. See
tests/test_tool_counts.py. Runscripts/generate_tool_docs.pyto regenerate this table.
| Tool | Purpose |
|---|---|
get_mod_index |
Build or query a structured index of the active mod. |
search_mod |
Search mod files by text, subdirectory, and file pattern. |
get_next_id |
Find the next available event, focus, decision, or character ID. |
check_id_exists |
Check whether an identifier is already present in the mod. |
set_mod_path |
Change the active mod without restarting the server. |
| Tool | Purpose |
|---|---|
validate_syntax |
Validate Clausewitz script or HOI4 localisation. |
get_latest_errors |
Parse recent HOI4 errors into structured output. |
fuzzy_edit |
Apply a guarded file edit using a sequence of matching strategies. |
get_loop_status |
Read the durable state of an autonomous validation loop. |
get_server_info |
Report HOI4-MCP version, MCP SDK version, Python version, and configured paths. |
| Tool | Purpose |
|---|---|
lookup_vanilla |
Query exact vanilla game data from the local SQLite index. |
generate_province_rgb |
Find an unused province color from definition.csv. |
| Tool | Purpose |
|---|---|
skill |
List or load a domain-specific HOI4 skill on demand. |
get_learned_rules |
Retrieve active rules relevant to the current task. |
record_mistake |
Store a correction or project convention for later sessions. |
resolve_mistake |
Deactivate a rule that is obsolete or superseded. |
export_learned_rules |
Export rules as JSONL or Markdown. |
import_learned_rules |
Import a shared JSONL rule set. |
session_review |
Review candidate lessons, remove duplicates, and detect conflicts. |
The server also exposes two MCP resources:
mod://descriptor— mod metadata (name, version, dependencies)logs://error_latest— last 50 lines of the HOI4 error log as structured JSON
Agent makes mistake → self-corrects → record_mistake()
↓
Next session: get_learned_rules() → rule loaded → mistake PREVENTED
Rules are stored locally in ~/.hoi4_mcp/learned_rules.db.
A rule records:
- the context in which it applies;
- the failed pattern or incorrect assumption;
- the required correction;
- severity and category;
- source and optional file location;
- occurrence count and resolution status.
The database starts with 14 HOI4-specific seed rules. Similar rules are deduplicated using token-overlap comparison, without an external machine-learning dependency. Both agent self-corrections and human corrections are captured as learning signals.
For a shared mod project, rules can be exported to a JSONL file and committed to the repository:
.hoi4-mcp-learned-rules.jsonl
Each line is a separate JSON object, which keeps reviews and merge conflicts manageable.
A typical session looks like this:
- Load the project rules with
get_learned_rules. - Inspect the mod with
get_mod_index. - Search for related implementations before creating new IDs or systems.
- Verify vanilla references with
lookup_vanilla. - Make the change.
- Run
validate_syntax. - Launch HOI4 and inspect
get_latest_errors. - Record any meaningful correction so it is available next time.
The supplied agent instructions formalize this into a broader development workflow, but the server does not require a specific model or editor.
- Python 3.10 or newer
pip- an MCP-capable client (VS Code with Copilot, Codex, Claude, or any MCP-compatible editor)
- a Hearts of Iron IV mod directory for project-specific tools
- a Hearts of Iron IV installation for vanilla lookups
The game installation is recommended but not required. Validation, error parsing, and learned-rule tools can still be used without a vanilla database.
git clone https://github.com/cpntodd/HOI4-MCP.git
cd HOI4-MCP/hoi4-mcp-server
python -m pip install -e .The package installs the hoi4-mcp and index-vanilla commands.
For reproducible installs, use the tested constraints file:
python -m pip install -c constraints.txt -e .index-vanilla --vanilla-path "/path/to/Hearts of Iron IV"The generated database is stored at:
~/.hoi4_mcp/vanilla.db
Rebuild it after a major HOI4 update if the underlying vanilla files have changed.
A workspace-level VS Code configuration can be placed in .vscode/mcp.json:
{
"servers": {
"hoi4-modder": {
"type": "stdio",
"command": "/absolute/path/to/python",
"args": [
"-m",
"hoi4_mcp.server",
"--mod-path",
"/absolute/path/to/your/mod",
"--vanilla-db",
"/absolute/path/to/.hoi4_mcp/vanilla.db"
]
}
}
}Use the Python executable from the environment in which hoi4-mcp-server was installed.
The server can also detect a mod workspace automatically:
{
"servers": {
"hoi4-modder": {
"type": "stdio",
"command": "/absolute/path/to/python",
"args": [
"-m",
"hoi4_mcp.server",
"--vanilla-db",
"/absolute/path/to/.hoi4_mcp/vanilla.db",
"--auto-detect-mod"
]
}
}
}--auto-detect-mod searches the current workspace and nearby parent directories for descriptor.mod or another .mod file.
See docs/SETUP.md for Windows setup, Codex configuration, environment variables, platform-specific paths, tested dependency versions, and troubleshooting.
| Mod | Size | Files | Time | Events | Loc Keys | Errors |
|---|---|---|---|---|---|---|
| Parliament GUI | 196K | 6 | <0.1s | 0 | 12 | 0 |
| Global Market | 2.8M | 15 | 0.4s | 16 | 638 | 0 |
| Greater Macedonia | 17M | 25 | 0.2s | 0 | 5,163 | 0 |
| Toolpack | 14M | 171 | 0.7s | 5 | 1,045 | 0 |
| Old World Blues | 3.6G | 2,745 | 21.4s | 1,360 | 124,607 | 0 |
| Kaiserreich | 1.2G | 2,156 | 51.0s | 19,558 | 252,105 | 0 |
| Vanilla 1.19.x | — | — | ~60s | 40,040 | — | 0 |
104 automated tests passing. All 6 reference mods index with zero errors.
See TEST-RESULTS.md for the full dataset and methodology.
HOI4-MCP/
├── AGENTS.md
├── SKILL.md
├── TEST-RESULTS.md
├── hoi4-modder.agent.md
├── docs/
│ ├── SETUP.md
│ └── USAGE.md
├── .agents/
│ └── skills/
├── hoi4-mcp-server/
│ ├── pyproject.toml
│ ├── constraints.txt
│ ├── src/hoi4_mcp/
│ │ ├── clausewitz/
│ │ ├── db/
│ │ ├── learning/
│ │ ├── tools/
│ │ └── server.py
│ └── tests/
├── scripts/
│ ├── setup.sh
│ ├── setup.ps1
│ └── generate_tool_docs.py
└── paradox_wiki/
- Setup guide — installation, client configuration, troubleshooting
- Usage guide — tool reference, common workflows, agent integration
- Test results — benchmarks across 6 reference mods + vanilla game
- Agent instructions — persona, workflow, and conventions for AI agents
- HOI4 syntax reference — Clausewitz language quick reference
HOI4-MCP is a development aid. It does not:
- guarantee that generated code is correct;
- understand every undocumented engine behavior;
- replace in-game testing;
- resolve design problems automatically;
- keep its vanilla database current without being rebuilt;
- prevent an external assistant from making unsupported claims outside the tool data.
The parser and validators are intentionally practical rather than complete reimplementations of the Clausewitz engine. When their output disagrees with Hearts of Iron IV, the game remains the final authority.
The project is currently pre-release. Interfaces, tool arguments, database schemas, and agent conventions may change while the workflow is being refined.
Current work is focused on:
- expanding coverage of HOI4 scripting systems;
- improving cross-platform setup and packaging;
- strengthening automated tests and CI;
- making agent skills usable across more MCP-capable assistants;
- improving validation and editing workflows for large mods.
Bug reports and focused pull requests are welcome.
Useful reports should include:
- the HOI4 version;
- the operating system and Python version;
- the MCP client being used;
- the smallest mod or file that reproduces the problem;
- the relevant server output or HOI4 log entry;
- the expected result.
For parser or validator changes, include a regression test whenever possible.
HOI4-MCP builds on Agentic-HOI4-Modding by klimPaskov.
That project established the original MCP and agent-assisted HOI4 modding approach used here. HOI4-MCP extends the idea with broader indexing, syntax validation, structured error handling, persistent learned rules, additional tools, and a larger reference library.
Copyright 2026 cpntodd.
Licensed under the GNU General Public License v3.0.