Skip to main content
Glama
jonathan-meyer

zmachine-mcp

by jonathan-meyer
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

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