Doom Mcp

io.github.gunnargrosch由 GitHub 帳號 gunnargrosch 發布v0.1.3更新於 Oct 24, 2026

Play DOOM via MCP - works with Claude Code, Cursor, and any MCP client

已驗證STDIO僅桌面

概覽

AI 產生的概覽

一個本機 MCP 伺服器,內嵌真正的 DOOM 引擎,讓 AI 助理能玩這款遊戲,並在每回合回傳狀態、敵人和物品資訊。

可以做什麼
啟動或重新開始 DOOM 遊戲,可選擇難度、章節和地圖,並在每回合後取得遊戲狀態、敵人情報、附近物品和門的資訊。透過按住移動、轉向、橫移、開火、使用和切換武器等動作並指定 tick 數來推進遊戲。將全解析度截圖儲存到系統暫存目錄並在預設圖片檢視器中開啟。既可以逐步指揮助理遊玩,也可以讓它自主行動。
適用情境
用於娛樂和實驗:在 Claude Code、Cursor 或其他 MCP 用戶端中觀看或操控 AI 助理玩 DOOM,觀察它如何根據收到的狀態和縮圖進行導航、瞄準和戰鬥。
執行需求
作為本機 stdio 程序執行,通常透過 npm 套件以 npx 啟動;包含 Windows x64 二進位檔。內建 Freedoom WAD 開箱即用;可透過 DOOM_WAD_PATH 環境變數提供自訂 IWAD。可選透過 DOOM_MCP_DEBUG 開啟偵錯日誌。從原始碼建置需要 Rust 工具鏈、GCC、Make、Git、curl 和 unzip。
安裝前請注意
每次動作回傳約 1,500-2,500 token 的文字和一個 PNG 縮圖,因此 50 次動作的工作階段可能消耗約 75,000-125,000 token 的 API 用量。截圖工具會向系統暫存目錄寫入檔案並在預設圖片檢視器中開啟。自訂 WAD 檔案從 DOOM_WAD_PATH 指定的路徑讀取。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Doom Mcp,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

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.

> Let's play DOOM!
  Starting E1M1 on medium difficulty...
  HP:100 Armor:0 | Pistol (key:2) | Ammo: 50b 0s 0r 0c | Kills:0 | E1M1  No enemies in sight. Exploring the corridor ahead.
> Go forward and find some enemies
  Sprinting down the hallway... I can see an opening ahead.
  HP:100 Armor:0 | Pistol (key:2) | Ammo: 50b 0s 0r 0c | Kills:0 | E1M1  ENEMIES IN SIGHT (aim for angle~0 then fire): Imp (HP:60) to your left (turn_left ~9) nearby
  There's an Imp to the left! Turning to face it...
> Shoot it!
  Aimed and firing!
  HP:100 Armor:0 | Pistol (key:2) | Ammo: 47b 0s 0r 0c | Kills:0 | E1M1  ENEMIES IN SIGHT (aim for angle~0 then fire): Imp (HP:15) AHEAD close
  Hit! The Imp is wounded (HP:15). One more burst should finish it.
  HP:95 Armor:0 | Pistol (key:2) | Ammo: 44b 0s 0r 0c | Kills:1 | E1M1  ITEMS: Stimpack (+10 HP) slightly to your right (turn_right ~4) point-blank (~3 ticks fwd+run to reach)  1 kill! Want to see a screenshot?

Read the blog post for the full story.


Table of Contents


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:

  1. Game state - HP, armor, ammo, kills, position, current weapon
  2. Enemy intel - visible enemies with human-readable direction, distance, and HP
  3. Nearby items - health, ammo, armor, weapons within pickup range
  4. Doors and switches - interactable linedefs detected within range
  5. 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.

mermaid
graph LR    A[MCP Client] -->|doom_start| B[doom-mcp binary]    A -->|doom_action| B    A -->|doom_screenshot| B    B -->|FFI| C[doomgeneric C engine]    C -->|frame buffer| B    B -->|game state + PNG| A

Quick Start

1. Register with your MCP client

Claude Code:

sh
claude mcp add doom --scope user -- npx -y doom-mcp

Cursor, Windsurf, or any MCP client - add to .mcp.json:

json
{  "mcpServers": {    "doom": {      "type": "stdio",      "command": "npx",      "args": ["-y", "doom-mcp"]    }  }}

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

ModeHow it worksBest for
You directYou give commands ("go forward", "open that door", "shoot the imp"). The AI executes one action at a time and describes what happens.Immersive guided play
AI autonomousThe AI makes all decisions - movement, combat, exploration. You watch and intervene if needed.Watching the AI play

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.

ParameterTypeDefaultDescription
skillint (1-5)3Difficulty: 1=baby, 2=easy, 3=medium, 4=hard, 5=nightmare
episodeint (1-4)1Episode number
mapint (1-9)1Map number

doom_action

Advance the game. All listed actions are held simultaneously for the tick duration.

ParameterTypeRequiredDescription
actionsstringyesComma-separated: forward, backward, turn_left, turn_right, strafe_left, strafe_right, fire, use, run, 1-7
ticksint (1-105)noGame ticks to advance. Default 7. At 35 ticks/sec: 7 ~ 0.2s, 35 ~ 1s

Gameplay notes:

  • fire holds the trigger for the full duration. Pistol auto-fires every ~10 ticks.
  • Turn and fire should be separate actions (turning while firing wastes ammo).
  • use opens 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

Environment VariableDescription
DOOM_WAD_PATHPath to a custom IWAD file (e.g., your own DOOM.WAD or DOOM2.WAD)
DOOM_MCP_DEBUGSet to 1 to enable debug logging to doom-mcp.log in the system temp directory

The bundled Freedoom WAD works out of the box, but the original DOOM shareware WAD has better levels and sprites. To use it:

  1. Download DOOM1.WAD from doomworld.com/classicdoom/info/shareware.php (legal, free)
  2. Set DOOM_WAD_PATH in your MCP config:
json
{  "mcpServers": {    "doom": {      "type": "stdio",      "command": "npx",      "args": ["-y", "doom-mcp"],      "env": {        "DOOM_WAD_PATH": "/path/to/DOOM1.WAD"      }    }  }}

If you own DOOM or DOOM 2, you can use those WADs the same way. To use any custom WAD:

json
{  "mcpServers": {    "doom": {      "type": "stdio",      "command": "npx",      "args": ["-y", "doom-mcp"],      "env": {        "DOOM_WAD_PATH": "/path/to/DOOM.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

src/main.rs         MCP JSON-RPC server over stdiosrc/doom.rs         Engine FFI wrapper: init, tick, frame capture, state extractionsrc/renderer.rs     PNG rendering (216-color palette thumbnails for MCP, full RGB for screenshots)src/paths.rs        WAD file discovery across platformssrc/log.rs          Debug logging to filebuild.rs            Compiles doomgeneric C sources via cc crate (whitelist approach)csrc/platform.c     DG_ callbacks, virtual time, key injection, enemy/item/door detection

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.

sh
git clone https://github.com/gunnargrosch/doom-mcp.gitcd doom-mcpbash scripts/setup.sh      # clones engines, downloads Freedoom WADcargo build --release       # compiles everything into a single binarycargo test                  # runs unit + integration tests

Register the local build for testing:

sh
claude mcp add doom --scope user -- ./target/release/doom-mcp

Enable debug logging:

sh
claude mcp add doom --scope user -e DOOM_MCP_DEBUG=1 -- ./target/release/doom-mcptail -f /tmp/doom-mcp.log   # Linux/macOS (Windows: %TEMP%\doom-mcp.log)

npm Package

Build the npm package locally:

sh
bash scripts/build-npm.sh   # copies binary + WAD into npm/cd npm && npm pack           # creates doom-mcp-0.1.2.tgz

Publish (requires npm account + NPM_TOKEN for CI):

sh
cd npm && npm publish

Credits


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.

來源:README.md,提交 adff214

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.1.3最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分