# Dmcp

> MCP server for AI dungeon masters in text-based RPGs

- **Type:** MCP server
- **Install:** `agentstack add mcp-shawnrushefsky-dmcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [shawnrushefsky](https://agentstack.voostack.com/s/shawnrushefsky)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [shawnrushefsky](https://github.com/shawnrushefsky)
- **Source:** https://github.com/shawnrushefsky/dmcp

## Install

```sh
agentstack add mcp-shawnrushefsky-dmcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

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

### Docker

Pull the image from GitHub Container Registry:

```bash
docker pull ghcr.io/shawnrushefsky/dmcp:latest
```

Or build locally:

```bash
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`

```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:

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

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

```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`:

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

---

### ChatGPT Desktop

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

**macOS**: `~/.chatgpt/mcp.json`

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

Or use Docker:

```json
{
  "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):

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

---

### Windsurf

Add to `~/.windsurf/config.json`:

```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:

```json
{
  "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:

```json
{
  "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:

```bash
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:
```bash
# 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:
```javascript
// 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](https://github.com/shawnrushefsky)
- **Source:** [shawnrushefsky/dmcp](https://github.com/shawnrushefsky/dmcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-shawnrushefsky-dmcp
- Seller: https://agentstack.voostack.com/s/shawnrushefsky
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.