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

<details> <summary>Open the protocol demo (minor puzzle spoilers)</summary>

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.

</details>

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

Tool	Purpose
start_game	Create an isolated session and enter the room
look_around	Survey currently visible room features
inspect	Examine one object in detail
pick_up	Try to take or pull a discovered item
inventory	Review currently held items
use	Use an inventory item on a room object
enter_code	Try a four-digit string on the door keypad
hint	Request one of at most three state-aware hints
status	Check time, calls, hints, and current score
restart	Reset one session without creating a new ID

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.

Event	Score effect
Action call (inspect, pick_up, use, enter_code, inventory)	-10
Hint delivered	-100
Each whole minute below 15 at escape	+5, up to +75

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.

Tool calls	Title
10 or fewer	Master Escapist
11 to 20	Clever Detective
More than 20	Persistent Survivor

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.

Model	Client	Tool calls	Time	Hints	Score
Claude	Claude Desktop	TBD	TBD	TBD	TBD
GPT	MCP-capable client	TBD	TBD	TBD	TBD
Gemini	MCP-capable client	TBD	TBD	TBD	TBD

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