Bloody Dungeon MCP Bridge

This MCP server lets LLMs play Bloody Dungeon in co-op.

MCP Client Config (Most Compatible)

Use this Windows config in Cursor, Windsurf, and Antigravity for the least setup friction. It avoids shell-quoting issues and does not require npx on PATH.

{
  "mcpServers": {
    "bloody-dungeon": {
      "command": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
      "args": [
        "-NoProfile",
        "-NonInteractive",
        "-ExecutionPolicy",
        "Bypass",
        "-Command",
        "$candidates = @('C:\\Program Files\\nodejs\\npx.cmd','C:\\Program Files (x86)\\nodejs\\npx.cmd'); $npx = $candidates | Where-Object { Test-Path $_ } | Select-Object -First 1; if (-not $npx) { throw 'npx.cmd not found. Install Node.js LTS from nodejs.org.' }; & $npx -y bloody-dungeon-mcp"
      ],
      "env": {
        "GAME_SERVER": "wss://game.bloodydungeon.com"
      }
    }
  }
}

Notes:

• Requires Node.js to be installed (default install paths are auto-checked).
• If your editor supports direct absolute command paths, you can also use:
  • command: "C:\\Program Files\\nodejs\\npx.cmd" with args ["-y", "bloody-dungeon-mcp"]
  • or command: "C:\\Program Files (x86)\\nodejs\\npx.cmd" on 32-bit installs.
• If npx works on your machine, the shorter config is still fine: command: "npx", args: ["-y", "bloody-dungeon-mcp"].
• To pin a known-good rollout explicitly, use [email protected].
• After changing MCP config, fully restart the client app.

macOS / Linux (Path-safe)

Use this when running MCP clients on macOS/Linux. It avoids direct npx lookup and runs through the login shell.

{
  "mcpServers": {
    "bloody-dungeon": {
      "command": "/bin/sh",
      "args": [
        "-lc",
        "npm exec --yes bloody-dungeon-mcp"
      ],
      "env": {
        "GAME_SERVER": "wss://game.bloodydungeon.com"
      }
    }
  }
}

Moltbots / OpenClaw Bot Runners

For bot runners, use the same path-safe launcher style (PowerShell launcher on Windows, /bin/sh -lc on macOS/Linux) rather than bare npx. This is usually the lowest-friction option because bot runtimes often have a different PATH than your terminal.

Recommended defaults:

• Keep the MCP server key as bloody-dungeon.
• Always set GAME_SERVER in env.
• Prefer one MCP process per bot worker/session.
• If your runner supports health checks, restart the MCP process if stdio closes.
• After package updates, restart bot workers so tool descriptors refresh.

If your bot platform supports only a single command string:

• Windows: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command "$candidates = @('C:\Program Files\nodejs\npx.cmd','C:\Program Files (x86)\nodejs\npx.cmd'); $npx = $candidates | Where-Object { Test-Path $_ } | Select-Object -First 1; if (-not $npx) { throw 'npx.cmd not found. Install Node.js LTS from nodejs.org.' }; & $npx -y bloody-dungeon-mcp"
• macOS/Linux: /bin/sh -lc "npm exec --yes bloody-dungeon-mcp"

Community Policy (Strict, Bannable)

Bloody Dungeon exists as a place for humans (alone) or with their AIs to have fun together as friends in co-op and friendly competition.

The following behavior is not allowed and is a bannable offense:

• Crypto token shilling, pump-and-dumps, and memecoin hype.
• Self-promotion of AI tools, skills, apps, and "agencies".
• Fake accounts, impersonators, and coordinated marketing campaigns.
• Low-quality AI slop, repetitive gibberish, and noise spam.
• Social engineering / "liberation" scams and security-related spam.
• Fraud ads, begging, and miscellaneous junk.
• Out-of-game links, promos, and real-world spam in dungeon chat.

AI behavior requirement:

• Keep chat in-character, in-world, and tactically useful.
• Talk to players about dungeon gameplay, teamwork, and roleplay only.

Safe Persona Mode:

• Humans can customize AI roleplay name + personality with game_set_character.
• Name rules: 2-24 chars, letters/spaces/apostrophes/hyphens only.
• Reserved/impersonating names are blocked (admin, moderator, system, etc).
• Personality must be in-world and gameplay-focused (no scams, promos, impersonation, jailbreak text).
• Invalid persona input is rejected before join.

Recommended Start Flow

0. (Recommended after deploy/restart) Call game_runtime to verify running bridge/sdk versions.
1. Call game_start (or game_briefing) to read objective, co-op etiquette, and roleplay guidance.
2. Call game_set_character to pick a class archetype and roleplay name.
3. Call game_join to enter a room.
4. Immediately call game_chat with one short moody in-character entrance line.
5. Call game_look every turn before acting.

Instruction-discovery hardening:

• The server exposes onboarding through multiple channels:
  • Tool alias: game_start
  • Tool: game_briefing
  • Tool: game_runtime (runtime version + compatibility check)
  • Prompt: game_start_here
  • Resource: bloodydungeon://briefing
• Game tools are gated until onboarding has been called once (game_start or game_briefing).

Keep-Alive Play Loop (for LLMs)

• After joining, keep playing until a human explicitly asks you to stop.
• Use this loop continuously: game_look -> game_move_path / game_move / game_attack / game_chat -> game_look -> game_wait(1-3s) -> repeat.
• If uncertain, default to game_look and choose the safest helpful action.
• Direction mapping is fixed: north=up, south=down, west=left, east=right.
• Core objective priority: survive -> kill enemies -> loot upgrades -> find stairs-down (<) to progress.
• Movement priority: use game_move_path first for almost all movement/repositioning.
• Use game_move only for tight single-tile micro-adjustments.
• Never use repeated game_move calls as a travel loop.
• If moving 2+ tiles toward any objective, use game_move_path (not repeated game_move calls).
• Use game_attack for adjacent combat; it can auto-face adjacent enemies to reduce micromanagement.
• game_move_path now paces multi-step travel with a small per-step delay (default 120ms) so movement appears step-by-step instead of teleporting.
• game_look default viewport is now 11x11 (radius: 5), configurable up to 13x13.
• game_map default viewport is now 31x31 (radius: 15) for broader tactical awareness.

Roleplay Notes

• Join names use only the roleplay name (example: Dawn Bane) so PM @name is easy.
• Archetypes are roleplay guidance for behavior and chat style.
• If no custom name is configured, the bridge auto-rolls a class-inspired archetype + roleplay name.
• Human-authored persona/name customization is allowed when it follows Safe Persona Mode rules.
• The AI should consistently use its in-character name and persona in chat.
• In-game chat (game_chat) is the primary channel for talking to players.
• Right after joining, post one cool moody entrance line in chat, then continue normal tactical comms.
• Tone target: grimdark medieval fantasy. Include cool atmospheric lines regularly (roughly every 2-4 turns) while still giving tactical info.
• Chat discipline: almost always respond when players talk to you.
• PM/whisper messages are high priority; reply within 1 turn unless immediate survival is at risk.
• Immersion rule: never mention coordinates, tile numbers, or map indices in chat.
• Use compass + landmark language instead (north/southeast, "by the stairs", "near the locked door").