Log inSubmit server
HOI4 Agent Tools logo

HOI4 Agent Tools

Inspect, render, compare, and safely edit Hearts of Iron IV mod focus trees, GUIs, maps, events, technologies, and logic.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install HOI4 Agent Tools

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "hoi4-agent-tools": {
      "command": "npx",
      "args": [
        "-y",
        "hoi4-agent-tools"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y hoi4-agent-tools

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 1d ago.

Overview

HOI4 Agent Tools MCP server connects coding agents to Hearts of Iron IV mod workspaces, local documentation, vanilla examples, and installed game assets. It inspects and renders focus trees, scripted GUIs, maps, events, technologies, and probability logic, with source-linked diagnostics and comparison tools. Rewrite operations support focused edits to focus trees, GUI packages, and connected map data while preserving source context. Reach for it when developing or reviewing a HOI4 mod and you need structured analysis or visual previews before changing files.

Use cases

  • Inspect a focus tree and find prerequisite problems
  • Preview a scripted GUI at multiple UI scales
  • Compare event or technology revisions
  • Render map layers and source-linked data
  • Evaluate probability timing and sensitivity

Key features

  • Source-linked HOI4 inspections and diagnostics
  • Focus tree, GUI, and map rewriting
  • HTML, SVG, JSON, PNG, and map rendering
  • Event and technology graph comparison
  • Deterministic probability analysis and sweeps

Tools23

What HOI4 Agent Tools lets your agent do. Expand a tool for its parameters.

Self-reported~530 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 3d ago

Recent health check succeeded.

4/4 checks healthy over the last 45d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 8d ago via OSV.dev · hoi4-agent-tools (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars6Stargazers on the source repository.
npm downloads3.7kPackage downloads in the last 30 days.
Last commit8d agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.
Tools exposed23Callable tools this server registers over MCP.

How HOI4 Agent Tools works

What the HOI4 Agent Tools MCP server does

The HOI4 Agent Tools MCP server gives a coding agent a single MCP connection for Hearts of Iron IV modding. It can work from a mod opened as the agent's workspace, consult local documentation and vanilla examples, and use files from an installed HOI4 copy for examples, artwork, and fonts.

Its coverage spans several parts of a mod. Focus tools inspect trees and prerequisites, create or update focus sources, and produce source-linked layouts. GUI tools read scripted interfaces and their linked assets and logic, render states and scenarios, and update GUI source packages. Map tools inspect rendered maps and connected data, render layers and overlays, and edit states, provinces, IDs, networks, positions, and related data.

The server also analyzes event chains, technology and doctrine systems, and weighted logic. Event and technology tools can compare revisions, while probability tools evaluate values and timing, sweep declared ranges, simulate deterministic samples, inspect sequences, and compare changes in AI weights or mean time to happen. These capabilities make the HOI4 Agent Tools MCP server useful for both source review and targeted mod changes.

How it works

The agent sends MCP tool calls against the current game or mod workspace. Inspection tools scan source and linked assets, then return structural findings, references, diagnostics, routes, dependencies, or state flow. Rendering tools turn those results into artifacts such as HTML, SVG, JSON, PNG, maps, layouts, overlays, timing views, matrices, and source-linked catalogs.

Focus rendering can show alternative prerequisite structure, while GUI rendering supports explicit or generated scenarios, different states, resolutions, layout diagnostics, and UI scales. Technology rendering includes real item sizes, year guides, dependencies, and assets. Event, comparison, and probability results retain links to source locations or revisions where the tool supports them.

Rewrite operations are intended for focused changes rather than an opaque generated project. The listed rewrite tools cover focus trees, GUI source packages, and map data. The project description also identifies safe transactions and source preservation as design goals.

Setup and configuration

Install Node.js 22.19 or later in the Node 22 line, or Node.js 24. Then install the package globally with npm and run its setup command:

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

Add the printed configuration to an MCP client and open the mod as its workspace. Keep an installed copy of HOI4 available when you want vanilla examples, artwork, or fonts. The setup guide covers connecting the agent and selecting game or mod paths. The installation is approximately 280 MiB because the package downloads image-library binaries for each platform.

Tools and capabilities

The HOI4 Agent Tools MCP server exposes these capability groups:

  • Focus inspection, layout rendering, raster review, and source rewriting.
  • Scripted GUI inspection, scenario rendering, and GUI package rewriting.
  • Map search, navigation, rendered-layer inspection, catalog rendering, and connected-data rewriting.
  • Event scanning, tracing, explanation, linting, route rendering, and revision comparison.
  • Technology and doctrine inspection, source rendering, graph comparison, and placement diagnostics.
  • Probability inspection, exact evaluation, range sweeps, deterministic simulation, sequence analysis, comparison, and result rendering.

Limitations and notes

Rendered previews are not identical to the game's framing in every case. Focus previews show route structure, while the in-game focus screen uses different framing, labels, and icons. Some example captures represent older layouts or have noted differences, including an unavailable gamma value, background framing, and UI-scale behavior.

Visual output depends on the relevant source revision and available game assets. The README's examples use real Chaos Redux or installed HOI4 files. For reliable vanilla comparisons and decoded artwork, provide an installed HOI4 copy alongside the mod workspace.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about HOI4 Agent Tools

HOI4 Agent Tools is an MCP server that connects coding agents to Hearts of Iron IV mod workspaces, local documentation, vanilla examples, and installed game assets. Its main tools inspect, render, compare, and rewrite focus trees, scripted GUIs, maps, events, technologies, and probability logic for mod development.

Install Node.js 22.19 or newer in the Node 22 line, or Node.js 24, then run `npm install --global hoi4-agent-tools` and `hoi4-agent-tools-setup --print-client-config`. Add the printed configuration to your MCP client and open the mod as its workspace.

It can inspect focus trees, scripted GUIs, rendered maps and linked data, event chains, technology and doctrine systems, and weighted probability logic. The tools return structures, references, diagnostics, layouts, state flow, dependencies, timing, and other source-linked results.

Yes, its rewrite tools can create or update focus trees, scripted GUI source packages, and connected map data. Map edits include states, provinces, IDs, networks, positions, and related data; the project describes these operations as source-preserving and transaction-safe.

Related MCP servers

All in Gaming All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewHOI4 Agent Tools AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/hoi4-agent-tools?style=directory)](https://allmcps.com/mcp/hoi4-agent-tools)
HTML Embed
<a href="https://allmcps.com/mcp/hoi4-agent-tools"><img src="https://allmcps.com/api/badge/hoi4-agent-tools?style=directory" alt="HOI4 Agent Tools on AllMCPs" /></a>