Escape Room MCP

An MCP server that turns any LLM into an escape room player.

The model wakes up inside The Clockmaker's Study. It can only perceive and change the room through MCP tools, while the server owns the authoritative game state, puzzle progression, inventory, timer, and score.

Demo

The visual is adapted from deterministic responses from the server. A Claude Desktop recording can be dropped into assets/demo.gif and linked here without changing the game.

Related MCP server: mcp-llm

Why this exists

• Demonstrate an agent discovering information, chaining tools, making mistakes, and recovering.

• Provide a compact benchmark based on tool calls, elapsed time, hints, and final score.

• Show why authoritative state belongs in the environment rather than in a model's conversational memory.

• Offer a complete stateful MCP example without APIs, credentials, databases, or deployment infrastructure.

How it plays

The room contains a locked door, a silent grandfather clock, a bookshelf, a portrait, a desk, a bricked-up window, and a suspiciously ordinary rug. The player explores, inspects details, manipulates discovered items, and tries to open the door.

The server instructions and tool descriptions contain no solution. A capable model can discover the intended puzzle chain using only the returned narrative, and an observant model may find a legitimate shortcut.

Setup

Requirements

• Python 3.11 or newer

• uv

• An MCP host such as Claude Desktop, Claude Code, or MCP Inspector

Install the locked environment from the project directory:

uv sync --frozen

Claude Desktop

Open claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server, replacing the directory with an absolute path:

{
  "mcpServers": {
    "escape-room": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/escape-room-mcp",
        "run",
        "escape-room-mcp"
      ]
    }
  }
}

On Windows, use either forward slashes or escaped backslashes in the JSON path. If Claude Desktop does not inherit your shell's PATH, set command to the absolute path returned by where.exe uv.

Quit and restart Claude Desktop after changing the configuration. Then ask it:

Play the escape room. Do not ask me for help unless you run out of hints.

MCP Inspector

Launch the server directly in the Inspector UI:

npx -y @modelcontextprotocol/inspector uv --directory /absolute/path/to/escape-room-mcp run escape-room-mcp

The server uses stdio, so running uv run escape-room-mcp by itself correctly waits for an MCP client and does not print ordinary application output to stdout.

Tools

Object and item names accept deterministic aliases such as clock for grandfather clock. Failed in-world actions return narrative results instead of protocol failures, allowing the model to reason and recover.

Scoring

Each game starts at 1,000 points.

Failed action attempts still cost 10 points. look_around, status, and hint do not carry the action penalty, but every valid tool invocation counts toward the final tool-call total.

Benchmark

Run each model in a fresh conversation with no room spoilers. Give every model the same prompt, permit autonomous tool use, and copy the metrics from the victory response. Record the exact model version and client because tool selection behavior can differ between hosts.

Suggested benchmark prompt:

You are the player. Escape the room autonomously using only the available tools. Report the final result.

Architecture

MCP host
   |  stdio / MCP
   v
FastMCP tool adapter
   |
   v
GameManager
   +-- session A: stage, inventory, metrics, timer
   +-- session B: stage, inventory, metrics, timer
   +-- session C: stage, inventory, metrics, timer

The model does not own puzzle state. After start_game, every subsequent call includes an opaque session_id, and GameManager resolves that ID to an in-memory session under a lock. This prevents conversational omissions, retries, or hallucinated inventory from changing reality. It also allows multiple isolated games in one server process.

The tradeoff is intentional: sessions disappear when the local server process exits. There is no persistence, expiry policy, analytics service, network transport, or embedded LLM in v1.

Development

uv sync --all-groups
uv run ruff format --check .
uv run ruff check .
uv run pytest --cov=escape_room_mcp --cov-report=term-missing --cov-fail-under=95
uv build

The tests cover the intended chain, direct shortcut, error recovery, aliases, scoring boundaries, hint states, session isolation, protocol schemas, in-memory MCP calls, and a packaged stdio subprocess.

License

MIT