The zandronum-mcp server lets an AI assistant control and interact with Zandronum (Doom engine) instances for game development, modding, testing, and debugging.
Engine Control
Launch/kill instances with custom IWAD, PWADs, maps, skill, and resolution settings
Run console commands and capture output
Pause/resume the game, advance simulation by tics (35 = 1 second)
Reset all instances and reap orphaned processes
Gameplay Interaction
Load maps, summon actors, give/take inventory items
Inspect any actor's live state (class, health, position, DECORATE state, inventory)
List actors within a radius, inspect aimed target
Press menu keys, navigate menus, type into text fields
ACS Scripting & Debugging
List, run, and profile ACS scripts and functions
Read/write world, global, and map-scope ACS variables and arrays
Index ACS source files for symbols, resolve script numbers/names to source locations
Extract function/script names from compiled BEHAVIOR lumps
Game State Inspection
Get player state (position, angle, sector, light level)
Read on-screen HUD elements (text, images, ACS HUD messages)
Query renderer info (backend, resolution, GL vendor), viewport dimensions, and HUD settings
Savegames & Demos
List savegames with metadata (title, map, engine, creation time)
Save/load game states; play back recorded demo files
Map Analysis (offline, no running game needed)
Read map format and entity counts from WAD files
Inspect sectors and linedefs, find sectors by tag
Debugging
Surface DECORATE/ACS compile errors and fatal startup errors from engine logs
Retrieve crash backtraces (signal, faulting address, symbolized stack trace)
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@zandronum-mcp Spawn a cyberdemon on MAP01 and give me a BFG"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Let an AI assistant supercharge Zandronum development from your editor: Write C++ code, ACS, DECORATE, fix bugs, the works.
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.
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
-configinstead of sharing the one system-widezandronum.ini, and instance numbers are scoped to your session — one editor window can never drive another's game. SetZANDRONUM_BRIDGE_PORTonly if you want to pin a specific port.
Verify with your preferred AI Agent by asking it, "Is Zandronum MCP loaded?" if it responds positively, then it is wired up.
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.
Related MCP server: Godot MCP
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.
Building the engine yourself, Linux, launching manually, running the server from source, contributing, etc: docs/ADVANCED.md.
Parse a directory of .acs source files and return symbol counts (scripts, functions, numeric defines). Reads files directly; no game needed.
Inputs: dir.
Run actorsnear and return actors within a radius (map units, default 512) of the player: class, health, position, and current sprite.
Inputs: radius, instance.
Run dumpactor and return an actor's live state: class, health, position, current DECORATE state (sprite/frame/tics, e.g. TNT1 A 0), inventory, and (for players) ready weapon + morph status. Defaults to the player; pass a TID for any actor.
Inputs: tid, instance.
Connect to a bridge-patched Zandronum that is ALREADY running — one you launched by hand, or from a terminal — and bind it to an instance number for the other tools. Only needed for engines this session didn't launch: launch_instance binds automatically. Defaults to this instance's conventional port.
Inputs: port, instance.
Read function and named-script names from a mod's compiled ACS (BEHAVIOR/library lumps) in a WAD or PK3 — for source-less mods. Numbered scripts have no names in bytecode (use find_acs_symbol with source for those).
Inputs: file (required).
Resolve a script number or a script/function name to its symbol(s) — name, number, file:line. Turns a profiler 'script 1017' into a source location.
Inputs: ref (required), dir.
Return all sectors whose tag/id matches (binary tag or UDMF id).
Inputs: map (required), tag (required), file.
Read an ACS world or global variable by index.
Inputs: index (required), scope (required), instance.
Return the signal, faulting address, and symbolized backtrace the bridge's crash handler captured the last time the engine crashed (segfault/abort/bus error/etc.). Use this when an instance dies unexpectedly — e.g. run_command reports the bridge closed. Empty if the instance has not crashed.
Inputs: instance.
Return one linedef by index, with its referenced sidedefs (textures + offsets) resolved.
Inputs: map (required), index (required), file.
Read one element of a map-scope ACS array by name and index.
Inputs: name (required), index (required), instance.
Read a map-scope ACS variable by name (searched across loaded modules).
Inputs: name (required), instance.
Return one sector's properties by index (all fields, format-native keys).
Inputs: map (required), index (required), file.
Read the engine's captured console log for an instance and surface DECORATE/ACS compile errors and fatal startup errors. Works even when the bridge never came up (e.g. the engine aborted on a bad script) — exactly when the other tools can't connect.
Inputs: instance.
Give an inventory item to the player.
Inputs: item (required), amount, instance.
Status bar Y position, status bar / HUD scale, alt HUD, crosshair.
Inputs: instance.
Run linetarget and return the actor the player is aiming at (class, health, spawn health).
Inputs: instance.
Stop a launched instance and detach from it. Asks the engine to quit itself first (a hard kill mid-render can wedge macOS GPU teardown and leave an unkillable process), then force-kills if it doesn't exit.
Inputs: instance.
Spawn a bridge-enabled Zandronum process with the given options and attach to it. Requires ZANDRONUM_EXE to be set.
Inputs: map, iwad, files, skill, +5 more.
Run dumpacsvars and return all non-zero ACS world/global variables, optionally filtered by scope.
Inputs: scope, instance.
Run dumpactors and return the registered DECORATE/actor classes as structured data.
Inputs: instance. Returns: actors
Run dumpfunctions and return named ACS functions across loaded modules.
Inputs: instance.
Run dumpmodules and return the loaded ACS modules (id + name). Map vars live only while a map is loaded.
Inputs: instance.
Run scriptstat and return the currently running ACS scripts and their states.
Inputs: instance. Returns: scripts
List .zds savegames in the save directory with metadata (title, map, engine, game wad, creation time) read from each save's PNG text chunks. No running game needed.
Inputs: dir.
Run dumpscripts and return every script across loaded modules (module, number, name, type, arg count).
Inputs: instance.
Run load to restore a savegame by name.
Inputs: name (required), instance.
Load a map by its lump name (e.g. MAP01, E1M1).
Inputs: mapName (required), instance.
Read a map from a WAD and return its format (doom/hexen/udmf) and entity counts. Reads the file directly — the game need not be running.
Inputs: map (required), file.
Press and release the left button at a position. Give toX/toY to DRAG: press at the first point, move through it, release at the second. double sends a double-click.
Inputs: x (required), y (required), toX, toY, +2 more.
Move the pointer to a screen position, in pixels from the top-left of the game window. Drives hover-only UI -- tooltips, hot states -- which nothing else here can reach.
Inputs: x (required), y (required), instance.
Wheel notches at the current pointer position. Positive scrolls up, negative down.
Inputs: notches (required), instance.
Run playdemo to play back a recorded .lmp demo. (Recording is via the -record launch arg, not a console command.)
Inputs: name (required), instance.
Run currentpos and return the player's position, angle, floor height, sector, and light level.
Inputs: instance.
Run acsprofile and return per-script/function execution stats (total instructions, runs, avg/min/max).
Inputs: sort, limit, instance.
Clear ACS profiling, wait N seconds, then return what ran during that window — what's hot right now rather than cumulative since map start.
Inputs: sort, limit, seconds, instance.
Run dumphud and return everything the engine painted last frame: HUD text strings (with screen x/y), images (by texture name + position), and active ACS HUD messages (full composed text, layer, position, remaining tics). Captures menus too.
Inputs: instance.
Active backend (software/opengl), GL vendor/shader model, resolution, fullscreen/vsync.
Inputs: instance.
Kill every instance this session launched, and reap engines ORPHANED by earlier sessions (whose launcher is gone) that could otherwise squat bridge ports. Engines belonging to another running editor window are left alone. Pass all:true to also kill those — only do that if you know no other session is using this engine build.
Inputs: all.
Send a raw console command to a running, bridge-patched Zandronum instance and return its captured output.
Inputs: text (required), instance.
Run (puke) an ACS script by number or name, with optional integer arguments.
Inputs: script (required), args, always, instance.
Run save to write a savegame (single-player / cooperative only). NOTE: saving heavily-scripted mods can crash the engine — All-out-War crashes on save; vanilla and simple maps save fine.
Inputs: name (required), instance, description.
Take a screenshot of the game and return it as an image so it can be viewed.
Inputs: instance.
Write an ACS world or global variable by index.
Inputs: index (required), scope (required), value (required), instance.
Write one element of a map-scope ACS array by name and index.
Inputs: name (required), index (required), value (required), instance.
Write a map-scope ACS variable by name.
Inputs: name (required), value (required), instance.
Set the engine's master pause flag directly. Use this to resume a backgrounded instance that auto-paused on focus loss, so the simulation keeps advancing while the MCP drives it.
Inputs: paused (required), instance.
Resume the game, let it run for the given number of tics (35 tics = 1 second), then pause again. Lets you advance the simulation a deterministic-ish amount to observe time-based effects (charging, projectiles, animations) without keeping the window focused.
Inputs: tics, instance.
Spawn an actor of the given class at the player's position.
Inputs: className (required), kind, instance.
Remove an inventory item from the player.
Inputs: item (required), amount, instance.
The 3D view window rect (x/y/width/height) and screenblocks size.
Inputs: instance.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 55 tools
Each tool has a narrowly defined purpose with detailed descriptions, but the sheer number of similar variable/script/map inspection tools creates occasional close calls (e.g., list_scripts vs list_running_scripts, get_acs_var vs get_map_var). Overall, most tools are clearly distinct.
Many tools use verb_noun (get_*, set_*, list_*, run_*), but others are bare noun phrases (renderer_info, actor_state, screenshot) and a few use nonstandard names (step, reset, verify_menu). The groupings like menu_* and mouse_* help, but the overall pattern is inconsistent.
55 tools is far beyond the typical well-scoped range, even for a comprehensive engine bridge. While each tool is specific, the sheer count makes the surface overwhelming and likely contains redundancy.
The surface covers the full lifecycle: instance management, console, scripting, variables, profiling, saves/demos, input simulation, HUD reading, actor manipulation, and map inspection. Minor gaps exist—no map editing, no world-input key events, no direct camera control—but they are not fatal for the stated purpose.
Build, run and publish 3D games in the Zero engine from Claude Code, Cursor or Codex, over MCP.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
AI game maker: build, run, screenshot and play-test Godot and retro console games in a live project
Savecraft serves real save game data and expert game knowledge to AI assistants.