mcpField
H
HOI4 Agent Tools

HOI4 Agent Tools

Local
github.comGames & Entertainment8Updated 3d ago
RepositoryVisit website

About HOI4 Agent Tools

HOI4 Agent Tools is an MCP server for coding agents that build and edit Hearts of Iron IV mods. It offers source-based previews, documentation lookup, script repair, and tools for creating maps and balancing AI choices.

Key features

  1. 01Builds focus trees, events, and decisions
  2. 02Edits maps and generates worlds
  3. 03Previews trees, windows, and maps
  4. 04Looks up game documentation
  5. 05Analyzes scripts and tunes AI choices

Use cases

  1. 01Creating a focus tree for a mod
  2. 02Generating a world from a reference image
  3. 03Finding and fixing broken script
  4. 04Previewing a map before writing it

MCP support

The MCP server exposes mod-editing, preview, documentation, and script-analysis tools to coding agents. For shared use, the same tools can be served over HTTP with tokens or OAuth.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "klimpaskov-hoi4-agent-tools": {
      "command": "npx",
      "args": [
        "-y",
        "hoi4-agent-tools"
      ]
    }
  }
}
Run commandnpx -y hoi4-agent-tools

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npmhoi4-agent-tools4.6.1

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

HOI4 Agent Tools

Watch the HOI4 Agent Tools demo

npm Node.js License Discord YouTube Ko-fi Download Issues

An MCP server that helps coding agents build and edit Hearts of Iron IV mods. 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.

For a new map, give it a cleaned local reference image and preview the interpreted geography before writing. The map workflow creates provinces, states, terrain, cities, countries, supply and a provisional starting scenario. Reviewed names and masks refine ambiguous artwork; offline validation is separate from native campaign acceptance. 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

  1. Install Node.js 22 (22.19 or later) or 24, and keep Hearts of Iron IV installed for vanilla files, artwork and fonts.

  2. Install the server:

    npm install --global hoi4-agent-tools

  3. Print the client configuration:

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

    Paste the globalInstall block into a JSON client such as Claude Code, Claude Desktop or Cursor, or the codexTomlGlobal block into Codex's config.toml.

  4. 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

A large focus tree rendered from mod source

Each pair shows a capture from the game next to the server's preview of the same source.

In gameServer preview
Focus tree in gameFocus tree preview
Infantry technology folder in gameInfantry technology folder preview
Video options in gameVideo options 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.

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

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.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.