Dmcp

DMCP - Dungeon Master MCP Service

An MCP (Model Context Protocol) server that enables AI agents to act as dynamic dungeon masters for text-based RPGs. Supports any setting or style with dynamically generated rule systems.

• [DMCP - Dungeon Master MCP Service](#dmcp---dungeon-master-mcp-service)
• [Features](#features)
• [Installation](#installation)
• [AI Self-Configuration Prompt](#ai-self-configuration-prompt)
• [From Source](#from-source)
• [Docker](#docker)
• [Setup by Platform](#setup-by-platform)
• [Claude Desktop](#claude-desktop)
• [Claude Code (CLI)](#claude-code-cli)
• [ChatGPT Desktop](#chatgpt-desktop)
• [Cursor](#cursor)
• [Windsurf](#windsurf)
• [Cline (VS Code Extension)](#cline-vs-code-extension)
• [Generic MCP Client](#generic-mcp-client)
• [Docker Configuration](#docker-configuration)
• [Testing with MCP Inspector](#testing-with-mcp-inspector)
• [HTTP Web UI](#http-web-ui)
• [Available Tools (170 total)](#available-tools-170-total)
• [Game Management (8 tools)](#game-management-8-tools)
• [Game Setup Interview (3 tools)](#game-setup-interview-3-tools)
• [Rules System (3 tools)](#rules-system-3-tools)
• [World Management (6 tools)](#world-management-6-tools)
• [Character Management (7 tools)](#character-management-7-tools)
• [Dice \& Checks (3 tools)](#dice--checks-3-tools)
• [Combat (7 tools)](#combat-7-tools)
• [Inventory (6 tools)](#inventory-6-tools)
• [Quests (5 tools)](#quests-5-tools)
• [Narrative (6 tools)](#narrative-6-tools)
• [Player Interaction (2 tools)](#player-interaction-2-tools)
• [Resources (7 tools)](#resources-7-tools)
• [Time \& Calendar (7 tools)](#time--calendar-7-tools)
• [Timers (6 tools)](#timers-6-tools)
• [Random Tables (7 tools)](#random-tables-7-tools)
• [Secrets \& Knowledge (9 tools)](#secrets--knowledge-9-tools)
• [Relationships (7 tools)](#relationships-7-tools)
• [Tags (5 tools)](#tags-5-tools)
• [Status Effects (8 tools)](#status-effects-8-tools)
• [Factions (8 tools)](#factions-8-tools)
• [Abilities \& Powers (9 tools)](#abilities--powers-9-tools)
• [Game Notes (9 tools)](#game-notes-9-tools)
• [Pause \& Resume (7 tools)](#pause--resume-7-tools)
• [Multi-Agent Collaboration (8 tools)](#multi-agent-collaboration-8-tools)
• [Image Storage (7 tools)](#image-storage-7-tools)
• [Display \& Theme (10 tools)](#display--theme-10-tools)
• [MCP Prompts (6 total)](#mcp-prompts-6-total)
• [Example Usage](#example-usage)
• [Starting a New Game](#starting-a-new-game)
• [NPC with Voice](#npc-with-voice)
• [Player Choices](#player-choices)
• [Character with Image Generation](#character-with-image-generation)
• [Story Export Workflow](#story-export-workflow)
• [Pause \& Resume](#pause--resume)
• [Multi-Agent Collaboration](#multi-agent-collaboration)
• [Data Storage](#data-storage)
• [License](#license)

Features

• Dynamic Rule Systems - Agent designs rules appropriate to the setting (fantasy, sci-fi, horror, etc.)
• Full Game State Management - Games, characters, locations, items, quests, combat
• HTTP Web UI - Built-in web interface for viewing character sheets, maps, images, and game state
• Voice Descriptions - NPC voice characteristics for TTS/voice mode integration
• Image Storage & Generation - Store images with metadata, serve via HTTP, structured visual descriptions for any image generator
• Player Choice System - Structured choices with multi-select and free-form input
• Narrative Logging - Event history for story continuity and export
• Dice & Checks - Flexible dice rolling and skill resolution
• Flexible Visualizations - Agents can render ASCII art, maps, or other visualizations as appropriate
• Factions & Politics - Organizations with resources, goals, and relationships
• Abilities & Powers - Spells, skills, powers with costs and cooldowns
• Status Effects - Buffs, debuffs with duration, stacking, and modifiers
• Custom Resources - Track currencies, reputation, sanity, or any numeric value
• Time & Calendar - In-game time tracking with scheduled events
• Random Tables - Reusable tables for encounters, loot, weather, names
• Secrets System - Hidden knowledge that can be revealed to characters
• Entity Relationships - Track attitudes, bonds, rivalries between any entities
• Tagging System - Universal tags for organizing any game entity
• Game Notes - Searchable DM notes with auto-generated recaps
• Pause & Resume - Save agent context for seamless game continuation
• Multi-Agent Collaboration - External agents can push updates for DM incorporation
• MCP Prompts - Reusable prompt templates for game setup, resume, and save verification

Installation

AI Self-Configuration Prompt

Copy and paste this prompt to any MCP-compatible AI assistant to have it guide you through setup:

Click to expand the setup prompt

I want to set up DMCP (Dungeon Master MCP) so we can play text-based RPGs together. DMCP is an MCP server that lets you act as a dungeon master with full game state management.

Repository: https://github.com/shawnrushefsky/dmcp
Docker image: ghcr.io/shawnrushefsky/dmcp:latest

Please help me configure this MCP server for my system. Here's what I need you to do:

1. First, determine what AI tool/platform I'm using (Claude Desktop, Claude Code, ChatGPT, Cursor, etc.) and my operating system.

2. Then guide me through the setup:
   - For Docker setup (recommended): Help me verify Docker is installed and configure the MCP server using the Docker image
   - For source setup: Help me clone the repo, run npm install && npm run build, and configure

3. The configuration should use these settings:
   - Docker: command "docker" with args ["run", "-i", "--rm", "-p", "3456:3456", "-v", "dmcp-data:/app/data", "ghcr.io/shawnrushefsky/dmcp:latest"]
   - Source: command "node" with args pointing to the dist/index.js file

4. After configuration, tell me to restart my AI application, then we can start playing!

Configuration file locations:
- Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
- Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
- Claude Code: .mcp.json in project root or ~/.claude/claude_desktop_config.json
- ChatGPT Desktop: ~/.chatgpt/mcp.json
- Cursor: Settings → MCP Servers
- Windsurf: ~/.windsurf/config.json

Once DMCP is configured, you'll have access to tools for managing games, characters, locations, items, quests, combat, dice rolls, and narrative events. You can run any style of RPG - fantasy, sci-fi, horror, or anything the player wants.

From Source

git clone https://github.com/shawnrushefsky/dmcp.git
cd dmcp
npm install
npm run build

Docker

Pull the image from GitHub Container Registry:

docker pull ghcr.io/shawnrushefsky/dmcp:latest

Or build locally:

docker build -t dmcp .

Setup by Platform

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "dmcp": {
      "command": "node",
      "args": ["/absolute/path/to/dmcp/dist/index.js"]
    }
  }
}

Restart Claude Desktop after saving.

---

Claude Code (CLI)

Project-level (recommended) - Create .mcp.json in your project root:

{
  "mcpServers": {
    "dmcp": {
      "command": "node",
      "args": ["/absolute/path/to/dmcp/dist/index.js"]
    }
  }
}

User-level - Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "dmcp": {
      "command": "node",
      "args": ["/absolute/path/to/dmcp/dist/index.js"]
    }
  }
}

Start a new Claude Code session to load the server.

Auto-approve all DMCP tools (optional) - Add to .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__dmcp__*"
    ]
  }
}

---

ChatGPT Desktop

ChatGPT desktop app supports MCP servers. Add to your configuration:

macOS: ~/.chatgpt/mcp.json

{
  "servers": {
    "dmcp": {
      "command": "node",
      "args": ["/absolute/path/to/dmcp/dist/index.js"]
    }
  }
}

Or use Docker:

{
  "servers": {
    "dmcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "3456:3456",
        "-v", "dmcp-data:/app/data",
        "ghcr.io/shawnrushefsky/dmcp:latest"
      ]
    }
  }
}

Restart ChatGPT after saving.

---

Cursor

Add to your Cursor MCP settings (Settings → MCP Servers):

{
  "mcpServers": {
    "dmcp": {
      "command": "node",
      "args": ["/absolute/path/to/dmcp/dist/index.js"]
    }
  }
}

---

Windsurf

Add to ~/.windsurf/config.json:

{
  "mcpServers": {
    "dmcp": {
      "command": "node",
      "args": ["/absolute/path/to/dmcp/dist/index.js"]
    }
  }
}

---

Cline (VS Code Extension)

Add to Cline's MCP settings in VS Code:

1. Open VS Code Settings
2. Search for "Cline MCP"
3. Add server configuration:

{
  "dmcp": {
    "command": "node",
    "args": ["/absolute/path/to/dmcp/dist/index.js"]
  }
}

---

Generic MCP Client

For any MCP-compatible client, configure:

• Command: node
• Arguments: ["/absolute/path/to/dmcp/dist/index.js"]
• Transport: stdio

---

Docker Configuration

For Docker-based MCP clients, use the ghcr.io image:

{
  "mcpServers": {
    "dmcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "3456:3456",
        "-v", "dmcp-data:/app/data",
        "ghcr.io/shawnrushefsky/dmcp:latest"
      ]
    }
  }
}

Flags:

• -p 3456:3456 exposes the HTTP web UI at http://localhost:3456
• -v dmcp-data:/app/data persists game data across container restarts

To use a different port, add -e DMCP_HTTP_PORT=8080 and change -p 8080:8080.

---

Testing with MCP Inspector

To test the server interactively:

npx @modelcontextprotocol/inspector node dist/index.js

---

HTTP Web UI

DMCP includes a built-in HTTP server with a Vue.js single-page application for viewing game content. It starts automatically alongside the MCP server.

• Default URL: http://localhost:3456
• Configure Port: Set DMCP_HTTP_PORT environment variable

Development Mode:

For hot-reload during development:

# Terminal 1: Run the MCP server
npm run dev

# Terminal 2: Run Vue dev server with hot-reload
npm run dev:client

The Vue dev server proxies API requests to the backend automatically.

Available Pages:

• / - Home page with all games
• /games/:id - Game overview with characters, locations, quests
• /games/:id/map - ASCII world map
• /games/:id/images - Image gallery
• /games/:id/history - Narrative event history
• /characters/:id - Character sheet with stats, inventory, images
• /locations/:id - Location details with exits and NPCs
• /quests/:id - Quest objectives and progress
• /images/:id - Full image view with metadata
• /images/:id/file - Raw image file (supports ?width=200&height=200 resize)

JSON API:

• GET /api/games - List all games
• GET /api/games/:id - Full game state
• GET /api/games/:id/map - Map data structure
• GET /api/characters/:id - Character data
• GET /api/characters/:id/sheet - Character sheet with ASCII art
• GET /api/locations/:id - Location data
• GET /api/games/:id/theme - Game theme configuration

Dynamic Theming:

The DM agent can customize the UI theme in real-time using display tools:

// Apply a preset theme globally
apply_theme_preset({ preset: "cyberpunk" })

// Or apply to a specific game
apply_game_theme_preset({ gameId: "...", preset: "noir" })

// Customize individual elements
set_display_config({ bgColor: "#1a1a2e", accentColor: "#00ff88", appTitle: "Neon Shadows" })

// Auto-apply theme based on game genre
auto_theme_game({ gameId: "...", genre: "sci-fi" })

Available presets: dark-fantasy, cyberpunk, cosmic-horror, high-fantasy, noir, steampunk, post-apocalyptic, pirate, western, modern, superhero, sci-fi

---

Available Tools (170 total)

Game Management (8 tools)

| Tool | Description | |------|-------------| | get_game_menu | Call first - returns existing games or starts new | | create_game | Start a new game with setting/style | | load_game | Resume an existing game | | list_games | Show all saved games | | get_game_state | Full game state overview | | update_game | Rename or update game name/setting/style | | set_game_title_image | Set title image for game (displayed in web UI) | | delete_game | Remove a saved game |

Game Setup Interview (3 tools)

| Tool | Description | |------|-------------| | get_interview_template | Get comprehensive game setup questionnaire | | save_game_preferences | Store player's game preferences | | get_game_preferences | Retrieve saved preferences |

Rules System (3 tools)

| Tool | Description | |------|-------------| | set_rules | Store agent-designed rule system | | get_rules | Retrieve current rules | | update_rules | Modify rules mid-game |

World Management (6 tools)

| Tool | Description | |------|-------------| | create_location | Add a new location | | get_location | Get location details | | get_location_by_name | Look up location by name (fuzzy matching) | | update_location | Modify a location | | list_locations | All locations in game | | connect_locations | Create paths between locations |

Character Management (7 tools)

| Tool | Description | |------|-------------| | create_character | New PC or NPC (with optional voice) | | get_character | Character details | | update_character | Modify character | | list_characters | Filter by player/NPC/location | | move_character | Change location | | modify_health | Damage or heal (mode: damage/heal) | | modify_conditions | Add and/or remove conditions in one call |

Dice & Checks (3 tools)

| Tool | Description | |------|-------------| | roll | Roll dice (e.g., "2d6+3") | | check | Skill/ability check | | contest | Opposed check between characters |

Combat (7 tools)

| Tool | Description | |------|-------------| | start_combat | Initialize encounter | | get_combat | Combat state | | get_active_combat | Current combat in game | | next_turn | Advance turn | | add_combat_log | Log combat action | | remove_combatant | Remove from combat | | end_combat | Resolve combat |

Inventory (6 tools)

| Tool | Description | |------|-------------| | create_item | Create new item | | get_item | Item details | | update_item | Modify item | | delete_item | Remove item | | transfer_item | Move between owners | | get_inventory | List items |

Quests (5 tools)

| Tool | Description | |------|-------------| | create_quest | New quest with objectives | | get_quest | Quest details | | update_quest | Modify quest | | modify_objectives | Add new objectives and/or mark complete in one call | | list_quests | Filter by status |

Narrative (6 tools)

| Tool | Description | |------|-------------| | log_event | Record story event | | get_history | Recent events | | get_summary | Story summary | | get_export_styles | List available narrative styles | | export_story | Export game overview with chapter summaries | | get_chapter_for_export | Get single chapter for subagent writing |

Player Interaction (2 tools)

| Tool | Description | |------|-------------| | present_choices | Show choices with multi-select & free-form | | record_choice | Log player's decision |

Resources (7 tools)

| Tool | Description | |------|-------------| | create_resource | Create

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shawnrushefsky
• Source: shawnrushefsky/dmcp
• License: MIT

Install and usage instructions live in the source repository linked above.