A
licenseNot graded
qualityA
maintenanceA Model Context Protocol (MCP) server for exploring, analyzing, and decompiling Java JAR files.
162 npm
7
MIT
HOI4 Agent Tools
by klimPaskov
Provides tools for modding Hearts of Iron IV, including focus tree editing, GUI design, and map transactions, integrating with Paradox Interactive's game development environment.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@HOI4 Agent Toolsscan the focus tree in my mod for errors"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-configAdd the printed configuration to your MCP client and open your mod as its workspace. The install is about 280 MiB, because npm fetches the image library's binaries for every platform to keep each install identical. 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 tools
Focus trees and alternative prerequisites
Focus tree | Supplied in-game capture | MCP source preview |
52 focuses |
|
|
111 focuses |
|
|
124 focuses |
|
|
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.
Folder | Supplied in-game capture | MCP source preview |
Vanilla infantry |
|
|
Mod wide cards |
|
|
The mod folder preview uses the source revision recorded with its screenshot and includes wide equipment cards. Armored-car artwork that installed DLC folders provide appears in the infantry preview. 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.
Interface | Supplied in-game capture | MCP source preview |
Vanilla video options |
|
|
Vanilla priority panel |
|
|
Mod management window |
|
|
The management window capture comes from an older layout. The video options preview has no observed gamma value, and the priority panel's capture frames its background differently.
Mod event log | Mod status panel | Mod status panel, second tab |
|
|
|
Vanilla decisions | Vanilla occupation |
|
|
The event log, status panel, 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.
Source map | Mod event chain |
|
|
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_doscore 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 35 tools. Your agent can select them from ordinary language; use the live tool schema for call parameters.
Tool | Purpose |
| Read focus trees, continuous-focus placement, and structural or reference problems. |
| Produce fast HTML, SVG, JSON, and source-linked layout artifacts. |
| Produce a PNG preview with decoded source icons. |
| Create or update a focus tree. |
| Read a scripted GUI and its linked assets and logic. |
| Render generated and explicit GUI scenarios, states, resolutions, and layout diagnostics. |
| Create or update a GUI source package. |
| Search, click, navigate, and inspect the complete rendered map and its linked data. |
| Render full-map layers, overlays, names, IDs, coordinates, and source-linked catalogs. |
| Create or update states, provinces, IDs, networks, positions, and connected map data. |
| Get compact, cited wiki and installed documentation pointers for a modding surface. |
| Search local documentation in plain words or script names; each result names its answering line. |
| Read one revision-bound section, with line continuation. |
| Find exact definitions, overrides and usages across game, DLC and mod, or the definition containing a file line. |
| Check a snippet or a whole mod file for syntax, command kinds, and scopes against local documentation. |
| Scan, trace, explain, lint, or assess event chains and their state flow. |
| Render source-linked event routes, options, timing, state, scope, and unresolved edges. |
| Compare event-chain topology and diagnostics between revisions. |
| Trace symbol and changed-file consumers across source systems and compare proposals. |
| Inventory and evaluate decisions or missions under declared scenarios and source changes. |
| Execute bounded source effects on a copied declared scenario and check assertions. |
| Check declarative package definitions, calls, registrations, assets, and case links. |
| Run named source and domain cases in resumable, revision-bound batches. |
| Inspect durable background work or retrieve its completed tool result. |
| Durably request cancellation of authorized background work. |
| Scan, trace, explain, lint, and assess technology and doctrine systems. |
| Render source layouts with real item sizes and year guides, plus dependencies and assets. |
| Compare technology graphs, placements, references, diagnostics, and source overlays. |
| Locate weighted logic and discover compatible adapters, candidates, and required inputs. |
| Evaluate supported weights, probability and timing models, and missing inputs. |
| Find sensitivity, breakpoints, cliffs, and rank reversals across declared ranges. |
| Run deterministic sampled analysis with confidence and convergence data. |
| Analyze declared recovery, caps, cooldowns, resets, timers, and terminal states. |
| Attribute AI-weight and MTTH changes between real or proposed source. |
| Render cached rankings, matrices, timing, sensitivity, sequence, and comparisons. |
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.
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessNo issues
Related MCP Connectors
A MCP server built for developers enabling Git based project management with project and personal…
An MCP server for deep research or task groups
MCP Server for JFrog, providing tools for development and artifact management.
MCP server for developer documentation, generated by doc2mcp.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA provider-agnostic MCP server that synchronizes work-in-progress between multiple coding sessions to prevent file conflicts.58 npm2MIT
- AlicenseAqualityBmaintenanceAn MCP server that empowers AI coding agents to work effectively with Minecraft mod development, providing static analysis of decompiled source code and runtime interaction with a running Minecraft instance.3145 npm14MIT
- FlicenseBqualityBmaintenanceAn MCP server that provides a bounded development workflow for ExileAPI plugins, enabling agents to detect compiler references, create linked Git repositories, and read build errors.19-