zandronum-mcp

Let an AI assistant supercharge Zandronum development from your editor: Write C++ code, ACS, DECORATE, fix bugs, the works.

Setup

1. Download the engine. Grab the build for your OS from Releases and unzip it anywhere.

   • Windows: zandronum-mcp-engine-windows-x64.zip.
   • macOS: zandronum-mcp-engine-macos-x64.zip (Intel build, runs under Rosetta 2).
   • Linux or a custom build: build it yourself.

2. Learn how to add MCP Servers to your preferred editor. In VS Code, put this in .vscode/mcp.json (Cursor, Claude Desktop, Windsurf, etc. uses something similar. Go look it up yourself or have your AI agent do it for you)

   {
     "servers": {
       "zandronum": {
         "command": "npx",
         "args": ["-y", "zandronum-mcp"],
         "env": {
           "ZANDRONUM_EXE": "C:/path/to/zandronum-mcp-hooks.exe"
         }
       }
     }
   }

   Point ZANDRONUM_EXE at the zandronum-mcp-hooks.exe or zandronum-mcp-hooks.app you just unzipped, then restart your chat session.

   Working on several checkouts at once? You don't need to do anything. The bridge port is derived from the engine path, so each build gets its own port range, each launched engine gets its own -config instead of sharing the one system-wide zandronum.ini, and instance numbers are scoped to your session — one editor window can never drive another's game. Set ZANDRONUM_BRIDGE_PORT only if you want to pin a specific port.

3. Verify with your preferred AI Agent by asking it, "Is Zandronum MCP loaded?" if it responds positively, then it is wired up.

4. You're done. You can now ask your agent to start working on the engine or start making mods. Remember, the MCP only works with the custom build of Zandronum you downloaded or built from step 1.

Tools

The server exposes tools (run, ACS, DECORATE, scripts, map & render inspection, saves, process control, etc). Your agent discovers them automatically; for a browsable list see README.tools.md.

Advanced

Building the engine yourself, Linux, launching manually, running the server from source, contributing, etc: docs/ADVANCED.md.