
Doom Mcp
io.github.gunnargroschPublished by GitHub account gunnargroschv0.1.3Updated Oct 24, 2026
Play DOOM via MCP - works with Claude Code, Cursor, and any MCP client
Overview
A local MCP server that embeds the real DOOM engine so an AI assistant can play the game, reporting state, enemies and items each turn.
- What you can do
- Start or restart a DOOM game, choosing difficulty, episode and map, and receive game state, enemy intel, nearby items and doors after each turn of play. Advance the game by holding movement, turning, strafing, firing, use and weapon-selection actions for a chosen number of ticks. Save a full-resolution screenshot to the temp directory and open it in the default image viewer. Play either by directing the assistant move by move or by letting it act autonomously.
- When to use it
- For entertainment and experimentation: watching or steering an AI assistant through DOOM in Claude Code, Cursor or another MCP client, and seeing how it navigates, aims and fights from the state and thumbnail it receives.
- Requirements
- Runs as a local stdio process, typically launched with npx from the npm package; a Windows x64 binary is included. A bundled Freedoom WAD works out of the box; a custom IWAD can be supplied via the DOOM_WAD_PATH environment variable. Optional debug logging via DOOM_MCP_DEBUG. Building from source needs a Rust toolchain, GCC, Make, Git, curl and unzip.
Installation
In SourceWeft
- Open Doom Mcp in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
DOOM via MCP
[MCP Registry] [npm version] [npm downloads] [License: MIT]
Can it run DOOM? Yes - your AI coding assistant can run DOOM.
Play DOOM in Claude Code, Cursor, or any MCP-compatible client. The AI sees the game, fights demons, navigates levels, and reports what's happening - or you direct it move by move.
Read the blog post for the full story.
Table of Contents
- How It Works
- Quick Start
- Play Modes
- Tools Reference
- Configuration
- FAQ
- Architecture
- Development
- Credits
- License
How It Works
A Rust MCP server embeds the real DOOM engine (doomgeneric) directly via FFI. No emulation, no child processes. Each tool call advances the game by a number of ticks and returns:
- Game state - HP, armor, ammo, kills, position, current weapon
- Enemy intel - visible enemies with human-readable direction, distance, and HP
- Nearby items - health, ammo, armor, weapons within pickup range
- Doors and switches - interactable linedefs detected within range
- Frame image - small PNG thumbnail for the AI's vision
The AI uses this information to navigate, fight, and explore. You can direct it or let it play autonomously.
Quick Start
1. Register with your MCP client
Claude Code:
Cursor, Windsurf, or any MCP client - add to .mcp.json:
2. Play
Open a new session and say:
"Let's play DOOM"
The AI will ask which mode you want, start the game on E1M1, and begin playing.
Play Modes
Tools Reference
doom_start
Start or restart DOOM. Safe to call at any time — if a game is already running it restarts cleanly without needing a new session.
doom_action
Advance the game. All listed actions are held simultaneously for the tick duration.
Gameplay notes:
fireholds the trigger for the full duration. Pistol auto-fires every ~10 ticks.- Turn and fire should be separate actions (turning while firing wastes ammo).
useopens doors and activates switches.- Weapon keys: 1=fists, 2=pistol, 3=shotgun, 4=chaingun, 5=rocket launcher, 6=plasma, 7=BFG.
doom_screenshot
Save a full-resolution 320x200 screenshot to the system temp directory and open it in the default image viewer. Does not advance the game (beyond a brief pause for the frame to settle).
Configuration
The bundled Freedoom WAD works out of the box, but the original DOOM shareware WAD has better levels and sprites. To use it:
- Download
DOOM1.WADfrom doomworld.com/classicdoom/info/shareware.php (legal, free) - Set
DOOM_WAD_PATHin your MCP config:
If you own DOOM or DOOM 2, you can use those WADs the same way. To use any custom WAD:
FAQ
Does this work on Windows? Yes. The npm package includes a Windows x64 binary. Register it the same way as on macOS/Linux.
Can I use my own DOOM WAD (DOOM.WAD, DOOM2.WAD)?
Yes. Set DOOM_WAD_PATH in your MCP config. The shareware DOOM1.WAD is free to download from doomworld.com and has much better levels than the bundled Freedoom. See the Configuration section for details.
How much does this cost in API tokens?
Each doom_action call returns ~1-2KB of text (game state + enemy info) plus a ~6KB PNG thumbnail. That's roughly 1,500-2,500 tokens per action. A typical gameplay session of 50 actions uses about 75,000-125,000 tokens.
Can the AI actually play DOOM well? It can navigate levels, find enemies, aim, and fight. It gets about 5-10 kills per session on E1M1 at medium difficulty. It struggles with enemies behind partial cover and navigating complex door sequences. It improves when you direct it.
Can I play a specific level?
Yes. Pass episode and map parameters to doom_start. For example, episode 1 map 3 would be episode:1, map:3.
What happens when I die? The engine reports HP:0 and offers a screenshot of the death screen. Currently there's no restart within a session - start a new conversation to play again.
Does this support multiplayer? Not yet. DOOM's multiplayer protocol could theoretically support multi-agent play, but it's not implemented.
Is the AI cheating? Can it see through walls?
No. Enemy detection uses DOOM's native line-of-sight check (P_CheckSight). The AI only sees enemies that would be visible on screen. Items are detected by proximity but the AI still has to walk over them to pick them up.
Architecture
The binary links the doomgeneric C engine at compile time. At runtime it is a single process with no subprocess spawning. Frames are read from a shared screen buffer and key inputs are injected through FFI.
Virtual time - The engine's clock is decoupled from wall time. Each doomgeneric_Tick() advances exactly one game tic (1/35th of a second), regardless of real elapsed time. This makes gameplay deterministic and prevents ticks from being skipped.
Enemy and item detection - The server iterates the engine's internal object list (thinker_t chain) to find nearby enemies and pickable items. Line-of-sight checks use Doom's native P_CheckSight(). Only visible enemies are reported to prevent "wallhack" cheating.
Development
Requires: Rust toolchain, GCC, Make, Git, curl, unzip.
Register the local build for testing:
Enable debug logging:
npm Package
Build the npm package locally:
Publish (requires npm account + NPM_TOKEN for CI):
Credits
- doomgeneric by ozkl - portable DOOM engine
- Freedoom - open-source IWAD files
- id Software - the original DOOM (GPL-2.0)
Changelog
See CHANGELOG.md for a detailed list of changes.
License
MIT for the MCP server code in this repository.
doomgeneric is GPL-2.0 licensed and is cloned at build time (not vendored). The Freedoom WAD is distributed under a BSD-style license.
Source: README.md at commit adff214
Tools
0Version history
1- v0.1.3LatestSep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts