cpntodd/hoi4-mcp

HOI4-MCP is a tool that helps an AI coding assistant become better at modding the video game Hearts of Iron IV. If you have ever tried to get an AI to help you write a game mod, you know the problem: the AI ends up guessing at IDs, miscounting brackets in the game's script files, and making the same mistakes over and over because it has no memory between sessions. This project tries to fix that. It works as an MCP server, which is a small program that gives an AI assistant extra tools it can call instead of just reading and writing text blindly. With this server running, the AI can look up an entire mod's structure in one call, search across mod files for text, check whether an ID is already in use before creating a new one, and validate the game's script syntax before you even launch it. It can also read the game's error log and sort the problems into categories so fixing them is faster. The standout feature is a learning system. When the AI makes a mistake and gets corrected, that correction can be saved as a permanent rule. The next time a session starts, those rules are loaded automatically, so the same error should not happen again. Rules can also be exported and shared with a modding team through git, so a whole group benefits from lessons one person already learned. Under the hood it includes a parser for the game's Clausewitz script format, a small database of vanilla game data such as focuses and events, and offline reference material from the Paradox wiki. It is written in Python, needs version 3.10 or newer, and the project reports 101 passing tests. It works on Linux, macOS, and Windows. This is a niche tool built specifically for people who mod Hearts of Iron IV using AI coding assistants like Claude, Cursor, or similar tools. It is not meant for general software development. The project is licensed under GPL-3.0, so any modified or shared versions must also stay open source under the same license. The full README is longer than what was shown.