HOI4 Agent Tools — Claude Code MCP server: features & setup
Connects coding agents to Hearts of Iron IV mod files. It creates focus trees, turns map sketches into playable provinces, repairs script bugs, and previews interfaces.
claude mcp add hoi4-agent-tools -- npx -y hoi4-agent-toolsWhat HOI4 Agent Tools does
This MCP server connects your coding agent to Hearts of Iron IV mod directories. The agent writes national focus branches, crafts custom events, and tunes AI decision weights. It also handles world generation from a local reference picture. The tool derives provinces, terrain zones, and basic supply routes from the provided graphic.
Instead of launching the game, you can preview focus layouts, tech trees, and interface windows right in the workspace. Edits apply directly to your local mod folder. Track changes with Git.
The server requires Node.js 22.19+ or Node.js 24. Without Hearts of Iron IV installed locally, the server cannot load base game textures, fonts, or vanilla assets.
What it helps with
- generate provinces, states, and supply networks from reference pictures
- render visual previews of focus trees, GUI windows, and tech folders
- write and edit scripts for national focuses, events, and decisions
- detect broken mod scripts and adjust AI decision weights
Example prompts for the agent
- Build a new focus tree branch for naval doctrine and show the preview.
- Generate provinces and states from the cleaned image
world_map.png. - Check scripts in
events/custom_events.txtfor syntax errors and tune AI weights.
How to install HOI4 Agent Tools
Platform CLI
claude mcp add hoi4-agent-tools -- npx -y hoi4-agent-toolsPlatform CLI
codex mcp add hoi4-agent-tools -- npx -y hoi4-agent-toolsConfig file
{
"mcpServers": {
"hoi4-agent-tools": {
"command": "npx",
"args": [
"-y",
"hoi4-agent-tools"
]
}
}
}Config file
{
"servers": {
"hoi4-agent-tools": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"hoi4-agent-tools"
]
}
}
}Platform CLI
gemini mcp add hoi4-agent-tools npx -y hoi4-agent-toolsStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about HOI4 Agent Tools
How do I install HOI4 Agent Tools in Claude Code?
Run claude mcp add hoi4-agent-tools -- npx -y hoi4-agent-tools in your terminal. This downloads the package via npx and registers it with the client.
What does HOI4 Agent Tools do?
It provides agent tools for editing Hearts of Iron IV mods. The tool builds focus trees, generates map provinces from drawings, creates UI previews, and checks script syntax.
Does this server run Hearts of Iron IV?
No. The server renders previews directly from mod scripts without running the game. You must test live clicks and gameplay inside the actual Hearts of Iron IV client.
