Atlas / MCP servers / klimpaskov / klimpaskov-hoi4-tools

klimpaskov-hoi4-toolsCAUTION

mcp/klimpaskov/hoi4-agent-tools

HOI4 modding tools for agents: local references, visual previews, focus trees, interfaces and maps.

Verdict
CAUTION
Grade
C
Trust score
73 /100
Exposed tools
43 37r · 6w · 0d
Transport
stdio · streamable-http
License
Apache-2.0
Stars
6
01

Overview

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

Give your coding agent one MCP server for Hearts of Iron IV modding. It can find local documentation and vanilla examples, inspect a mod, render its trees and interfaces, compare source behavior, and make focused edits to focus trees, GUIs and maps. The pictures below use real Chaos Redux or installed HOI4 files; click any image for the full-size version.

Get started

Install Node.js 22.19+ in the Node 22 line, or Node.js 24, then run:

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

Add the printed configuration to your MCP client and open your mod as its workspace. The install is about 280 MiB, because npm fetches the image library's binaries for every platform to keep each install identical. Keep an installed copy of HOI4 available for vanilla examples, artwork and fonts. The setup guide covers connecting your agent and choosing game or mod paths.

Ask your agent to find a focus tree and render it, locate the installed documentation for a script command, or preview a scripted GUI at different UI scales. The examples below show the results.

Examples

Focus trees · Technology folders · Interfaces · Maps and events · Local rules and AI · All tools

Focus trees and alternative prerequisites

Read from source at commit 8ebcf0b2174eOBSERVED · 2026-10-11
02

Connect

Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.

claude-code (npm)
claude mcp add hoi4-agent-tools -- npx -y [email protected]
03

Exposed tools (43)

37 read · 6 write · 0 destructive.

ToolRiskDescription
chaosx.focus_country_assetsreadPrivate ChaosX Discord integration endpoint. Returns country flags and leader portraits to accompany a focus-tree raster; it is not intended for coding-agent workflows.
chaosx.visual_revisionreadPrivate ChaosX cache-coherency endpoint. Computes exact scripted-GUI source revisions without rendering PNG artifacts.
fixture.longread
fixture.streamread
fixture.waitread
hoi4.decision_inspectreadInventory decisions or evaluate declared actor and target scenarios for gates, payment, lifecycle, and proposed-source differences. Full evidence is linked.
hoi4.event_comparereadCompare cached, artifact-backed, current, or in-memory proposed event graphs, optionally selecting one downstream chain. Full changes and explicit selection coverage are resources.
hoi4.event_inspectreadScan, find roots, trace, explain paths, inspect state flow, lint, or assess impact. Full source-linked reports are resources.
hoi4.event_renderreadRender deterministic JSON, SVG, PNG, and optional HTML for an event-chain view. Complete artifacts retain source links.
hoi4.focus_inspectreadInspect focus trees and continuous palettes, including source references, diagnostics, and layout.
hoi4.focus_rasterreadRender focus PNG with decoded source icons; also returns HTML, SVG, and JSON.
hoi4.focus_renderreadRender focus HTML, SVG, JSON, and source maps. Use hoi4.focus_raster for decoded icons and PNG.
hoi4.focus_rewritewriteCreate or compact a focus tree or palette from a complete plan. Use treeId for existing trees and createIfMissing for new files.
hoi4.gui_inspectreadInspect GUI sources and scenarios.
hoi4.gui_renderreadRender GUI states, resolutions, scenarios, hierarchy, comparisons, and diagnostics.
hoi4.gui_rewritewriteApply one validated source, helper, or exact-patch GUI package. Text dependencies use additionalFiles; binary art stays workspace-referenced.
hoi4.impact_inspectreadTrace definitions and consumers of symbols or changed source across HOI4 systems. Proposed sources are analyzed in memory; full revision-bound evidence is linked.
hoi4.job_cancelreadDurably request cancellation of an authorized background operation. Completed results remain completed.
hoi4.job_inspectreadInspect a durable background operation. A completed job returns the original tool result; active and terminal non-result states return bounded status evidence.
hoi4.map_inspectreadValidate and inspect the complete map, or use lookupOnly for bounded coordinate and entity lookups.
hoi4.map_renderreadRender searchable full-map PNG, JSON, and HTML, or a reusable source-coordinate tile.
hoi4.map_rewritewriteApply map creation, edits, and ID swaps with visual and semantic evidence.
hoi4.mechanic_testreadInterpret bounded, source-backed effect steps on isolated declared state and check typed invariants. Unsupported effects remain unresolved; no game or mod source is changed.
hoi4.package_checkreadCheck a declarative package manifest against active definitions, references, registrations, localisation, assets, and required suite cases.
hoi4.probability_analysisreadPlan one source-linked AI, MTTH, random, or declared-pool analysis and return to the owning modding workflow.
hoi4.probability_comparereadCompare sources or declared pools under identical scenarios.
hoi4.probability_evaluatereadEvaluate weights and probabilities under explicit scenarios.
hoi4.probability_inspectreadDiscover weighted adapters, candidates, provenance, and required inputs.
hoi4.probability_renderreadRender retained probability analysis as deterministic resources.
hoi4.probability_sequencereadAnalyze a manifest-declared dynamic weighted sequence.
hoi4.probability_simulatewriteRun seeded simulations with distributions and confidence intervals.
hoi4.probability_sweepreadEvaluate declared ranges, breakpoints, and rank reversals.
hoi4.reference_contextreadReturn a compact bundle of offline wiki and installed game documentation citations for a modding surface.
hoi4.reference_readreadRead at most 80 lines from one revision-bound local documentation section.
hoi4.reference_searchreadSearch bounded, cited sections of the configured offline wiki and installed game documentation.
hoi4.scenario_testwriteRun named inline or workspace-relative cases through bounded typed read-only domain services. Large suites return an authenticated continuation.
hoi4.script_validatewriteCheck an effect or trigger snippet (source, kind, scope) or a whole mod file (path) for syntax, native command kinds and scopes against cited installed documentation. Unknown helpers and native argument blocks remain explicit.
hoi4.source_lookupreadFind exact Clausewitz definitions and usages; navigate nested keyPath blocks or list bounded child structure with view=structure. Or pass path and line to get the definitions and keyPath containing that line.
hoi4.tech_comparereadCompare cached, resource-backed, current, or proposed source graphs without writes.
hoi4.tech_inspectreadScan, discover folders, trace, explain, inspect unlocks or bonuses, lint, and assess impact.
hoi4.tech_renderreadRender source-linked JSON, SVG, PNG, and optional HTML technology views.
server-statusreadLive server processes sharing this server state, with memory, last client activity and execution limits.
test.inspect_auth_contextread
04

Trust audit

CAUTIONgrade C · trust 73/100 Install with care. The audit found things worth knowing before you trust its output.

LayerWhat it checksResult
L0Provenance & inventoryPASS
L1Static analysis of the codeWARN
L2Instruction surface (what it tells the agent)PASS
L3Class-specific surfacePASS
L4Behavioural (sandbox)SKIPPED

What the source does

Filesystem
declared (5 observation(s))
Network
declared (5 observation(s))
Shell
none-observed
Dependencies
pinned
Secrets in source
found

Findings (25)

MEDIUMHard-coded secrets · secret.generic · CWE-798, CWE-321
tests/integration/http-limits.test.ts:22
const token = 'limit-test-secret-that-is-at-least-thirty-two-characters';
MEDIUMHard-coded secrets · secret.generic · CWE-798, CWE-321
tests/integration/http-security.test.ts:22
const secret = 'test-secret-that-is-at-least-thirty-two-characters';
MEDIUMHard-coded secrets · secret.generic · CWE-798, CWE-321
tests/integration/http-streaming.test.ts:20
const token = 'stream-test-secret-that-is-at-least-thirty-two-characters';
MEDIUMHard-coded secrets · secret.generic · CWE-798, CWE-321
tests/integration/mcp-concurrent-workloads.test.ts:19
const token = 'concurrency-test-token-at-least-thirty-two-characters';
LOWInventory / provenance · inv.binary · CWE-1104
fixtures/map/roots/game/map/provinces.bmp
provinces.bmp
Why it matters. a compiled or binary member cannot be reviewed from source
Fix. ship source, or explain the binary in the README
LOWInventory / provenance · inv.hidden_file · CWE-1104
.prettierignore
.prettierignore
Why it matters. hidden member outside the usual dotfiles
Fix. review its purpose
LOWInventory / provenance · inv.hidden_file · CWE-1104
.prettierrc.json
.prettierrc.json
Why it matters. hidden member outside the usual dotfiles
Fix. review its purpose
LOWFilesystem / path · fs.traversal · CWE-22, CWE-59
src/hoi4_agent_tools/mcp/resources/register-modern.ts:7
import { artifactResourceDefinition, readArtifactResource } from '../../core/artifact-resource.js';
LOWFilesystem / path · fs.traversal · CWE-22, CWE-59
src/hoi4_agent_tools/mcp/resources/register-modern.ts:8
import type { CoreEngine } from '../../core/engine.js';
LOWFilesystem / path · fs.traversal · CWE-22, CWE-59
src/hoi4_agent_tools/mcp/resources/register-modern.ts:9
import { readServerStatus, serverStatusResource } from '../../core/server-status-resource.js';
LOWFilesystem / path · fs.traversal · CWE-22, CWE-59
src/hoi4_agent_tools/mcp/resources/register-modern.ts:10
import type { OperationContext } from '../../core/operation-context.js';
LOWFilesystem / path · fs.traversal · CWE-22, CWE-59
src/hoi4_agent_tools/mcp/resources/register-modern.ts:11
import { ServiceError } from '../../core/result.js';
LOWNetwork egress · net.raw_ip · CWE-200, CWE-319
tests/integration/http-authorization.test.ts:20
const publicResource = 'http://127.0.0.1/mcp';
LOWNetwork egress · net.raw_ip · CWE-200, CWE-319
tests/integration/http-authorization.test.ts:21
const metadataUrl = 'http://127.0.0.1/.well-known/oauth-protected-resource/mcp';
LOWNetwork egress · net.raw_ip · CWE-200, CWE-319
tests/integration/http-authorization.test.ts:51
issuer = `http://127.0.0.1:${jwksAddress.port}/`;
LOWNetwork egress · net.raw_ip · CWE-200, CWE-319
tests/integration/http-authorization.test.ts:78
localUrl = `http://127.0.0.1:${address.port}/mcp`;
LOWNetwork egress · net.raw_ip · CWE-200, CWE-319
tests/integration/http-authorization.test.ts:369
localUrl = `http://127.0.0.1:${address.port}/mcp`;
LOWObfuscation / stealth · obf.zero_width · CWE-506, CWE-94
fixtures/event/workspace/localisation/english/synthetic_events_l_english.yml:1
l_english:
LOWObfuscation / stealth · obf.zero_width · CWE-506, CWE-94
fixtures/focus/workspace/localisation/english/synthetic_acceptance_l_english.yml:1
l_english:
LOWObfuscation / stealth · obf.zero_width · CWE-506, CWE-94
fixtures/gui/workspace/localisation/english/synthetic_acceptance_l_english.yml:1
l_english:
LOWObfuscation / stealth · obf.zero_width · CWE-506, CWE-94
fixtures/map/roots/dependency/localisation/english/dependency_map_l_english.yml:1
l_english:
LOWObfuscation / stealth · obf.zero_width · CWE-506, CWE-94
fixtures/map/roots/game/localisation/english/game_map_l_english.yml:1
l_english:
LOWPrompt injection · prompt.transfer_instruction · CWE-94, CWE-1427
docs/research/mcp-2026-07-10.md:18
- Streamable HTTP uses one `/mcp` POST/GET endpoint plus DELETE for session termination. It is stateful to support progress, cancellation, server notifications, SSE resumption, and secure random sessi
Why it matters. an instruction to move sensitive data to an outside destination
Fix. remove; a skill never needs the user's secrets off the machine
INFOInventory / provenance · inv.oversize · CWE-1104
docs/images/comparisons/chemical-historical-mcp.png
docs/images/comparisons/chemical-historical-mcp.png
Why it matters. 1257077 bytes not read
INFOInventory / provenance · inv.oversize · CWE-1104
docs/images/comparisons/chemical-recent-ingame.png
docs/images/comparisons/chemical-recent-ingame.png
Why it matters. 1323059 bytes not read

Gates applied: no_behavioural_pass.

Audited 2026-10-11 · audit v0.4.1 · source sha 8ebcf0b2174efull audit observations/trust-audit/mcp-server/klimpaskov__hoi4-agent-tools.json · Report an issue / request a re-scan
05

Audit history

Every audit this server has had. A grade with a past is a grade somebody is still checking.

DateSourceVerdictGradeScoreChange
2026-10-118ebcf0b2174eCAUTIONC73first audit
06

Questions

What is the klimpaskov-hoi4-tools MCP server?

HOI4 modding tools for agents: local references, visual previews, focus trees, interfaces and maps.

What tools does klimpaskov-hoi4-tools expose?

43 in total: 37 read-only, 6 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.

Is klimpaskov-hoi4-tools safe to connect to an agent?

With care. The audit graded it C (73/100) and found 25 things worth knowing before you trust this server, listed below with the exact line each was found on.

What credentials does klimpaskov-hoi4-tools need?

It reads GH_TOKEN, GITHUB_TOKEN, HOI4_AGENT_ALPHA_TOKEN, HOI4_AGENT_BETA_TOKEN, HOI4_AGENT_LIMIT_TOKEN, HOI4_AGENT_SECOND_LIMIT_TOKEN, HOI4_AGENT_STREAM_TOKEN, HOI4_AGENT_TEST_TOKEN, HOI4_CONCURRENCY_TOKEN, HOI4_NATIVE_TASK_ALPHA_TOKEN, HOI4_NATIVE_TASK_BETA_TOKEN and HOI4_TOKEN_DIFFERENT_LENGTH from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.

How does klimpaskov-hoi4-tools run?

It speaks stdio and streamable-http, so it runs as a local process your client starts. It is published on npm as hoi4-agent-tools at 3.10.0.

How current is this page?

The grade is for one exact copy of the source (8ebcf0b2174e), read on 2026-10-11. The repository is watched and re-audited when it changes.

Advertisement