zmachine-mcp

An MCP server for playing Z-Machine text adventure games (Zork, Hitchhiker's Guide, etc.) with AI agents.

Three interfaces expose the same game engine:

• MCP — stdio or HTTP transport, so AI assistants like Claude can play text adventures
• REST API — programmatic session management and input/output
• WebSocket — real-time output streaming

A built-in status page at / shows server health, active sessions, and MCP setup instructions.

Quick Start

npm install

Place your Z-Machine story files (.z3, .z4, .z5, .z7, .z8, .zblorb) in a folder and point to it:

export STORIES=../stories

Then start the server:

# Development (auto-reload, server on :3000, Vite on :5173)
npm run dev

# Production
npm run build && npm start

Open http://localhost:3000 to see the server status page.

MCP Integration

Claude Desktop (stdio)

npm run start:stdio

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "zmachine": {
      "command": "npx",
      "args": ["tsx", "src/server/main.ts", "--stdio"],
      "env": {
        "STORIES": "/path/to/your/stories"
      }
    }
  }
}

HTTP Transport

When running in HTTP mode, the MCP endpoint is available at POST /mcp.

MCP Tools

Tool	Description
list_games	List available story files
start_game	Start a new session; returns session ID and opening text
send_input	Send a command; returns the game's response
get_session_info	Get session state and status line
quit_game	End a session

REST API

Interactive documentation is available at /api/docs when the server is running. The raw OpenAPI spec is at /api/openapi.yml.

Method	Endpoint	Description
GET	/api/status	Server status, uptime, active sessions
GET	/api/games	List available games
GET	/api/sessions	List all active sessions with their IDs, game, state, and status line
POST	/api/sessions	Create a new game session
POST	/api/sessions/:id/input	Send input to a session
DELETE	/api/sessions/:id	End a session

WebSocket

Connect to ws://localhost:3000/ws?session=<id> for real-time output streaming.

Configuration

Environment Variable	Default	Description
STORIES	../stories	Path to folder containing Z-Machine story files
PORT	3000	HTTP server port
REDIS_URL	—	Redis connection URL for session persistence
DEBUG	—	Set to zmachine:* to enable debug logging

Redis Persistence (optional)

Set REDIS_URL (e.g. redis://localhost:6379) to persist sessions and save data to Redis. Without it, sessions are in-memory only and lost on restart.

Development

npm run dev           # Dev server with auto-reload
npm test              # Run tests
npm run test:coverage # Tests with coverage report
npm run typecheck     # TypeScript type checking

Project Structure

src/
  server/
    main.ts            — Entry point (HTTP or stdio mode)
    mcp-server.ts      — MCP tool definitions
    rest-server.ts     — Express REST API
    ws-server.ts       — WebSocket server
    session-manager.ts — Loads stories, manages sessions
    game-session.ts    — Single game session (wraps Z-Machine VM)
    glkote-async.ts    — Custom GlkOte for synchronous I/O capture
    redis-store.ts     — Optional Redis persistence
  client/
    main.ts            — Status page (polls /api/status)
    index.css          — Status page styles
  __tests__/           — Jest test suites

Tech Stack

• Runtime: Node.js + TypeScript (ESM)
• Z-Machine: ifvms + glkote-term
• Server: Express 5, WebSocket (ws)
• MCP: @modelcontextprotocol/sdk
• Client: Vanilla TypeScript, Vite
• Testing: Jest + ts-jest