HOI4 Agent Tools
io.github.klimPaskov/hoi4-agent-tools · 10 stars · TypeScript · Apache-2.0
MCP server Build HOI4 mods: focus trees, events, decisions, worlds, GUI previews, docs and AI balance.
Install
The repo has no one-line install. Follow its README.
Published as
- npm
hoi4-agent-toolsstdio
From the server's entry in the official MCP Registry.
Files
HOI4 Agent Tools
An MCP server that helps coding agents build and edit Hearts of Iron IV mods.
Quick start · npm · Changelog · Contributing · Security
Make focus trees, events and decisions. Edit maps and generate a new world. Preview windows, trees and maps, find the right rule in the docs, fix broken script and balance AI choices.
What it does
Your agent can build and edit focus trees, events, decisions and maps, and generate a new world from a reference image (map guide). It previews focus trees, technology folders, windows and maps, finds the right rule in the game's documentation, fixes broken script and tunes AI choices. You describe what you want; the agent picks the right tools.
Quick start
-
Install Node.js 22 (22.19 or later) or 24, and keep Hearts of Iron IV installed for vanilla files, artwork and fonts.
-
Install the server:
npm install --global hoi4-agent-tools
-
Print the client configuration:
hoi4-agent-tools-setup --print-client-config
Paste the
globalInstallblock into a JSON client such as Claude Code, Claude Desktop or Cursor, or thecodexTomlGlobalblock into Codex'sconfig.toml. -
Open your mod folder as the agent's workspace and tell it what you want to build or fix.
The setup guide covers several mods, explicit game paths, local wiki snapshots and troubleshooting with --discover and --diagnose.
Watch the Agent Tools demo or use HOI4 Mod Setup to install and connect the server for your mod. Part of the HOI4 modding toolkit with Agentic HOI4 Modding (skills and instructions for your agent) and HOI4 Live Tools (testing in the running game).
Examples
Each pair shows a capture from the game next to the server's preview of the same source.
| In game | Server preview |
|---|---|
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
See more in the examples gallery.
Tools
The server gives your agent previews, documentation, script analysis and editing tools. The agent combines them with its file editor to build events and decisions, repair scripts and adjust AI weights. The tool reference lists exact names, arguments and results for integrations.
A session lists the core tools by default: documentation search, source lookup, script validation, the error log, the mod health check and localisation. They fit in about 8,000 tokens of the agent's context. Set HOI4_AGENT_TOOLS_PROFILES to core,map, core,advanced or all in the client's server entry for the world map tools or the focus, GUI, event, technology and probability editors (tool profiles).
FAQ
Where do edits go? Changes are written to your mod folder; use Git to review or undo them.
Does it run the game? No. Previews come from mod source; test gameplay in HOI4 to see live clicks, AI choices and timing.
Configuration
Started inside a mod folder, the server needs no configuration file.
hoi4-agent-tools-setup --init writes one when you work on several mods or the game is not found automatically.
For remote or shared use, hoi4-agent-tools-http serves the same tools over HTTP with tokens or OAuth.
See the configuration reference and the HTTP guide.
Documentation
- Setup and configuration
- Examples and tool reference
- Guides: local references, focus trees, scripted GUIs, maps, events, technology, AI weights and timing, decisions and impact, mechanic and package tests
- Background jobs and HTTP
- Development, changelog and security policy
- Documentation index
Development
npm ci npm run check
See the contributing guide and the development guide.
License
Apache-2.0; see LICENSE and the third-party notices. Hearts of Iron IV artwork belongs to Paradox Interactive; this project is unaffiliated with Paradox Interactive. The in-game captures were supplied for these comparisons.
Facts
- Kind
- MCP server
- Group
- Uncategorized
- Stars
- 10
- License
- Apache-2.0
- Language
- TypeScript
- Last push
- 2026-11-09
- Forks
- 1
- MCP Registry
- io.github.klimPaskov/hoi4-agent-tools
- Topics
- coding-agents, hearts-of-iron-iv, hoi4, mcp, modding, model-context-protocol
Next on this shelf
- 6428hexveroio.github.maximilianfeix/hexveroElectron release diff for security review: what changed in IPC, contextBridge, windows and hosts.10
- 6430Singapore MCP by Olanoio.github.olano-ai/mcp-singaporeSingapore public data, transport, rail, property, business, economy, weather, and analytics.10
- 6431Google Search Consoleio.github.onlymoein/google-search-console-mcpSearch Console analytics, hourly data, URL inspection and sitemaps, with guards for API quirks.10
- 6433AMH Cloudflare Ops MCP by WTio.github.pain2hustle/cloudflare-ops-mcpThe bridge from K2 agents through Wrangler to your master AI - safe, approval-gated Cloudflare ops.10
- 6434pardeslineio.github.pardesline/pardesline3D vision and medical imaging: 43 datasets with licences, 73 algorithms on clouds, meshes, CT/MRI10
- 6435Pine Script v6 Documentationio.github.paulieb89/pinescript-mcpPine Script v6 documentation lookup, function validation, and linting for AI code generation10







