# HOI4 Agent Tools [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/klimPaskov/hoi4-agent-tools  
**GitHub Stars:** 8  
**npm Downloads (last month):** 4188  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hoi4-agent-tools

## Description
Source-preserving HOI4 focus, scripted GUI, and map tools with safe transactions.

## Tools
Capabilities this server exposes over MCP:

- **hoi4.focus_inspect** — Read focus trees, continuous-focus placement, and structural or reference problems.
- **hoi4.focus_render** — Produce fast HTML, SVG, JSON, and source-linked layout artifacts.
- **hoi4.focus_raster** — Produce a high-fidelity PNG review with decoded source icons.
- **hoi4.focus_rewrite** — Create or update a focus tree.
- **hoi4.gui_inspect** — Read a scripted GUI and its linked assets and logic.
- **hoi4.gui_render** — Render generated and explicit GUI scenarios, states, resolutions, and layout diagnostics.
- **hoi4.gui_rewrite** — Create or update a GUI source package.
- **hoi4.map_inspect** — Search, click, navigate, and inspect the complete rendered map and its linked data.
- **hoi4.map_render** — Render full-map layers, overlays, names, IDs, coordinates, and source-linked catalogs.
- **hoi4.map_rewrite** — Create or update states, provinces, IDs, networks, positions, and connected map data.
- **hoi4.event_inspect** — Scan, trace, explain, lint, or assess event chains and their state flow.
- **hoi4.event_render** — Render source-linked event routes, options, timing, state, scope, and unresolved edges.
- **hoi4.event_compare** — Compare event-chain topology and diagnostics between revisions.
- **hoi4.tech_inspect** — Scan, trace, explain, lint, and assess technology and doctrine systems.
- **hoi4.tech_render** — Render source layouts with real item sizes and year guides, plus dependencies and assets.
- **hoi4.tech_compare** — Compare technology graphs, placements, references, diagnostics, and source overlays.
- **hoi4.probability_inspect** — Locate weighted logic and discover compatible adapters, candidates, and required inputs.
- **hoi4.probability_evaluate** — Evaluate exact values, probabilities, timing, bounds, and unresolved inputs.
- **hoi4.probability_sweep** — Find sensitivity, breakpoints, cliffs, and rank reversals across declared ranges.
- **hoi4.probability_simulate** — Run deterministic sampled analysis with confidence and convergence data.
- **hoi4.probability_sequence** — Analyze declared recovery, caps, cooldowns, resets, timers, and terminal states.
- **hoi4.probability_compare** — Attribute AI-weight and MTTH changes between real or proposed source.
- **hoi4.probability_render** — Render cached rankings, matrices, timing, sensitivity, sequence, and comparisons.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "hoi4-agent-tools": {
    "command": "npx",
    "args": ["-y","hoi4-agent-tools"]
  }
}
```

## Documentation

## What HOI4 Agent Tools does

HOI4 Agent Tools connects an MCP-capable coding agent to a Hearts of Iron IV mod workspace. Its tools work with source files and, when available, installed vanilla game files for artwork, fonts, and reference data. The server covers several modding areas:

- Focus trees, including focus placement, continuous focuses, references, and layout artifacts.
- Scripted GUIs, linked assets, logic, states, scenarios, and layout diagnostics.
- Maps, including provinces, states, IDs, networks, positions, overlays, names, and coordinates.
- Events and technology systems, with source-linked inspection, rendering, tracing, linting, and comparison.
- Weighted logic and timing analysis through evaluation, sensitivity sweeps, simulations, sequences, and comparisons.

Rewrites can create or update focus trees, GUI source packages, and connected map data. Renderers produce formats such as HTML, SVG, JSON, PNG, and source-linked visual artifacts, depending on the tool.

## How it works

Start the server from a mod folder and describe the change or investigation to the agent. The agent selects MCP tools, combines their results with its file editor, and writes changes back into the mod directory. Inspection and rendering operate on the source, allowing an agent to examine structure, references, dependencies, assets, routes, and unresolved diagnostics before making edits.

Map generation can begin with a cleaned local reference image. The workflow interprets geography for preview, then can create provinces, states, terrain, cities, countries, supply data, and a provisional starting scenario. Reviewed names and masks can be used to refine ambiguous artwork.

The server also supports an HTTP entry point for remote or shared use, with tokens or OAuth. Local use is configured through the provided setup command and client-specific output.

## Setup and configuration

Install Node.js 22.19 or later, or Node.js 24, and keep Hearts of Iron IV installed if the mod needs vanilla artwork, fonts, or files. Install the package globally:

```bash
npm install --global hoi4-agent-tools
```

Generate client configuration with:

```bash
hoi4-agent-tools-setup --print-client-config
```

Use the generated `globalInstall` block with Claude Code, Claude Desktop, or Cursor. Codex uses the generated `codexTomlGlobal` block in `config.toml`. Open the mod folder as the agent workspace before requesting changes.

A configuration file is optional when the server starts inside a mod folder. Run `hoi4-agent-tools-setup --init` for multiple mods or when automatic game discovery needs explicit configuration. The setup utilities also provide discovery and diagnostic modes.

## Tools and capabilities

The MCP tool groups expose the following operations:

- `focus_inspect`, `focus_render`, `focus_raster`, and `focus_rewrite` for focus-tree analysis, visualization, raster review, and editing.
- `gui_inspect`, `gui_render`, and `gui_rewrite` for scripted GUI source packages and rendered scenarios.
- `map_inspect`, `map_render`, and `map_rewrite` for rendered-map exploration, overlays, catalogs, and connected map data.
- `event_inspect`, `event_render`, and `event_compare` for event-chain tracing, route rendering, diagnostics, and revision comparison.
- `tech_inspect`, `tech_render`, and `tech_compare` for technology and doctrine graphs, layouts, assets, and dependency analysis.
- `probability_inspect`, `probability_evaluate`, `probability_sweep`, `probability_simulate`, `probability_sequence`, `probability_compare`, and `probability_render` for weighted logic, timing, bounds, sensitivity, sampled analysis, and change attribution.

## Limitations and notes

Results are based on mod source and previews rather than a running game session. The server cannot verify live clicks, in-game AI choices, or gameplay timing. Review edits with Git, and test the resulting mod in Hearts of Iron IV for native campaign behavior and runtime acceptance.

_Full upstream README: https://allmcps.com/mcp/hoi4-agent-tools/readme_