HOI4 Agent Tools

Give your coding agent one MCP server for Hearts of Iron IV modding. It can find local documentation and vanilla examples, inspect a mod, render its trees and interfaces, compare source behavior, and make focused edits to focus trees, GUIs and maps. The pictures below use real Chaos Redux or installed HOI4 files; click any image for the full-size version.

Get started

Install Node.js 22.19+ in the Node 22 line, or Node.js 24, then run:

npm install --global hoi4-agent-tools
hoi4-agent-tools-setup --print-client-config

Add the printed configuration to your MCP client and open your mod as its workspace. Keep an installed copy of HOI4 available for vanilla examples, artwork and fonts. The setup guide covers connecting your agent and choosing game or mod paths.

Ask your agent to find a focus tree and render it, locate the installed documentation for a script command, or preview a scripted GUI at different UI scales. The examples below show the results.

Related MCP server: Session Collab MCP

Examples

Focus trees · Technology folders · Interfaces · Maps and events · Local rules and AI · All 34 tools

Focus trees and alternative prerequisites

Dotted connectors in the MCP preview mark focuses where either preceding focus satisfies one prerequisite group. The tree previews show route structure; the game's focus screen has different framing, labels and icons. The focus guide explains inspection, rendering and edits, and the comparison details retain source revisions.

Technology folders and card artwork

Render a technology folder. Check card sizes, artwork, links and missing placements.

The chemical comparison uses the source revision recorded with the screenshot and includes wide equipment cards. The technology comparison records its source revision, and the technology guide covers inspection and doctrine paths.

Scripted interfaces

Preview an interface with its game assets and fonts. Check states, text clipping and clickable areas at 100% and 125% UI scale.

The Tag Manager screenshot comes from an older layout. The Options preview has no observed gamma value, and Škoda's game capture frames its background differently.

The Event Log, Chaos Meter, decision and occupation previews use declared states or positions for layout review. They are source previews, not observations of a running campaign. See the interface gallery for full images and fidelity notes, and the GUI guide for scenario inputs.

Maps and event chains

Find Brandenburg on the map, inspect its provinces and neighbours, and show the affected source files before a change.

Trace an event's options and follow-up events. Point out unresolved calls and link each route to its source.

The map guide covers connected province, state, supply and railway data. The event guide covers routes, scope, timing and unresolved references.

Local rules and AI weights

Find the installed documentation for save_event_target_as, read the relevant section, and show a vanilla usage with file and line references.

Compare this decision's ai_will_do score before and after a change in peace and war. List missing conditions separately from known results.

The reference example found the installed effect documentation first and read its relevant 12-line section instead of loading whole wiki pages. The AI guide covers supported weights, chance and timing models; a source score alone does not establish an AI click probability. The examples guide has more prompt details.

Complete tool list

The default server exposes 34 tools. Your agent can select them from ordinary language; use the live tool schema for call parameters.

Set HOI4_AGENT_TOOLS_CHAOSX=1 to expose two optional Chaos Redux workflow tools: chaosx.focus_country_assets and chaosx.visual_revision. The tool guide explains results, linked artifacts and long operations.

How it fits your workflow

The server works through your coding agent and follows the mod workspace you provide. It keeps large renders and reports in linked files, and retrieves relevant documentation sections instead of whole manuals. Your repository instructions and review process still apply.

Inspection and rendering do not edit the mod. The focus, GUI and map rewrite tools can change source files after checking the proposed edit. The server does not launch or control the game; previews and source tests cannot prove live clicks, AI choices or engine timing.

Documentation · Tool reference · Contributing · Security

Apache-2.0 licensed. Hearts of Iron IV artwork belongs to its respective owners; this project is unaffiliated with Paradox Interactive.