<p align="center">
  <img src="assets/zandromcp.png" alt="zandronum-mcp" width="200">
</p>

# zandronum-mcp

![version](https://img.shields.io/npm/v/zandronum-mcp?label=version&color=blue)
![last release](https://img.shields.io/github/release-date/rc4l/ZandronumMCP?label=last%20release&color=blue)
![tools](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/rc4l/ZandronumMCP/main/.github/badges/tools.json)

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](https://github.com/rc4l/ZandronumMCP/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](https://github.com/rc4l/ZandronumMCP/blob/main/docs/ADVANCED.md).

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)

   ```json
   {
     "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.

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

5. 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](https://github.com/rc4l/ZandronumMCP/blob/main/README.tools.md).

## Advanced

Building the engine yourself, Linux, launching manually, running the server
from source, contributing, etc: 
[docs/ADVANCED.md](https://github.com/rc4l/ZandronumMCP/blob/main/docs/ADVANCED.md).