# HOI4 Agent Tools

Connects coding agents to Hearts of Iron IV mod files. It creates focus trees, turns map sketches into playable provinces, repairs script bugs, and previews interfaces.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 7
- Author: klimPaskov
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/klimPaskov/hoi4-agent-tools
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/hoi4-agent-tools

## What it does

This MCP server connects your coding agent to Hearts of Iron IV mod directories. The agent writes national focus branches, crafts custom events, and tunes AI decision weights. It also handles world generation from a local reference picture. The tool derives provinces, terrain zones, and basic supply routes from the provided graphic.

Instead of launching the game, you can preview focus layouts, tech trees, and interface windows right in the workspace. Edits apply directly to your local mod folder. Track changes with Git.

The server requires Node.js 22.19+ or Node.js 24. Without Hearts of Iron IV installed locally, the server cannot load base game textures, fonts, or vanilla assets.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add hoi4-agent-tools -- npx -y hoi4-agent-tools
```

### Codex

**Platform CLI**
```bash
codex mcp add hoi4-agent-tools -- npx -y hoi4-agent-tools
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "hoi4-agent-tools": {
            "command": "npx",
            "args": [
                "-y",
                "hoi4-agent-tools"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "hoi4-agent-tools": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "hoi4-agent-tools"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add hoi4-agent-tools npx -y hoi4-agent-tools
```

## When to use it
- generate provinces, states, and supply networks from reference pictures
- render visual previews of focus trees, GUI windows, and tech folders
- write and edit scripts for national focuses, events, and decisions
- detect broken mod scripts and adjust AI decision weights

## Example prompts
- Build a new focus tree branch for naval doctrine and show the preview.
- Generate provinces and states from the cleaned image `world_map.png`.
- Check scripts in `events/custom_events.txt` for syntax errors and tune AI weights.

## Similar
- [Pascal 3D Editor](https://affpapa.org/en/nevibecode/mcp/pascal-3d-editor.md) — MCP server · ★ 25137
- [Unity-MCP](https://affpapa.org/en/nevibecode/mcp/unity-mcp.md) — MCP server · ★ 4534
- [mcp](https://affpapa.org/en/nevibecode/mcp/sceneview-mcp.md) — MCP server · ★ 1349
- [Gearboy MCP Server](https://affpapa.org/en/nevibecode/mcp/gearboy-mcp-server.md) — MCP server · ★ 1218
- [ChiR24-unreal_mcp_server](https://affpapa.org/en/nevibecode/mcp/chir24-unreal-mcp-server.md) — MCP server · ★ 982
- [Nova3D](https://affpapa.org/en/nevibecode/mcp/nova3d.md) — MCP server · ★ 732

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md