DM20 Protocol

A comprehensive Model Context Protocol server for managing AI-assisted Dungeons & Dragons campaigns, built with FastMCP 2.9+.

• For Groups — A toolkit to help run campaigns more effectively

• For Solo Players — A complete virtual D&D experience with AI as the DM

• For Worldbuilders — Tools to create rich, interconnected game worlds

Status: Under active development. See Roadmap for what's next.

Features

• Campaign Management — Create and switch between multiple campaigns

• Character Builder — Auto-populated characters from loaded rulebooks (Standard Array, Point Buy, Roll 4d6, Manual). Starting spells and properly typed equipment auto-populated from rulebook data. Creation dice rolls recorded on the character sheet

• Character Creation Wizard — Guided step-by-step or Quick Build modes. Asks player name, character level, race, class, ability scores, skills, equipment, and spells. Completeness validation after creation ensures nothing is missing

• Level-Up & Progression — Automatic HP, class features, spell slots, ASI/feats on level-up

• Character Sheets — Full D&D 5e stats, inventory, spellcasting, death saves, creation roll history

• Sheet Sync — Bidirectional Markdown↔JSON sync: edit YAML frontmatter in Obsidian or any editor, DM approves changes

• D&D Beyond Import — Import characters from D&D Beyond (URL or JSON file)

• Rest & Recovery — Long rest, short rest with hit dice, spell slot management, death saves

• NPCs & Locations — Rich world-building with relationships and connections

• Quest Tracking — Objectives, status, rewards, and branching paths

• Combat System — Initiative, turns, attack/spell resolution, active effects, concentration tracking, ASCII tactical maps, AoE targeting, encounter builder

• Compendium Packs — Export/import campaign content as portable JSON packs with conflict resolution (skip, overwrite, rename), selective filtering, and full backups

• Narrative Fog of War — Progressive location discovery (undiscovered → glimpsed → explored → fully mapped), sensory hints for hidden features, narrator-aware descriptions

• Party Knowledge — Track what the party knows about the world, with source attribution and bidirectional NPC knowledge sharing

• Multi-User Permissions — Role-based access (DM, Player, Observer) with output filtering, session coordination, and private messaging — zero overhead in single-player

• Party Mode — Multi-player web relay: players connect from their phones/tablets via QR code, each getting a personal game interface with narrative feed, character sheet, and action input — all filtered by the permission system. WebSocket real-time push, combat turn coordination, reconnection with message replay, and JSONL queue persistence

• Rules Edition Selection — Choose between D&D 2024 revised rules and 2014 classic rules when creating a campaign. Both SRD and 5etools data sources loaded automatically

• Multi-Source Rulebooks — Load rules from SRD, Open5e, 5etools, or custom JSON

• PDF Rulebook Library — Import and query your own PDFs and homebrew content

• Bilingual Play — Italian/English D&D terminology resolution (500+ terms)

• Session Notes — Per-session summaries, XP, loot, attendance

• Adventure Log — Searchable timeline of all campaign events

• Context Auto-Refresh — /dm:refrill saves the session and provides instructions to clear context. Two-layer protection: proactive DM trigger at ~65% + automatic PreCompact hook at ~83.5%

• Dice & Utilities — Rolls, XP calculations, rules lookup

• 86 MCP Tools — Full list in the User Guide

Installation

3 Steps to Play D&D

You don't need to install anything beforehand. One command sets up everything:

bash <(curl -fsSL https://raw.githubusercontent.com/Polloinfilzato/dm20-protocol/main/install.sh)

The installer asks a few questions (which MCP client you use, where to put your data), handles all dependencies automatically, and configures everything. When it's done:

cd ~/dm20    # go to your play directory
claude       # start Claude Code — the MCP server connects automatically

That's it. You're ready to play. Type /dm:help to see what you can do, or jump straight in with /dm:start.

Using Claude Desktop instead? Just restart it after installation — the MCP server is already configured. Use the MCP tools directly instead of slash commands.

The installer offers two modes. Most users should pick "User" — it's the default:

Running bash install.sh from inside an existing clone? The installer auto-detects it and switches to Developer mode.

Supported platforms: macOS (Apple Silicon & Intel), Linux (x86_64/arm64), Windows via WSL. See Installer Details for the full breakdown.

Want to know what happens under the hood? The Installer Guide covers the full architecture, every edge case we handle, and why we built it this way.

Compatibility

This server implements the open Model Context Protocol standard. It works with any MCP-compatible client — not just Claude.

We're confident in cross-platform support (the installer and server are designed for it), but we can only mark combinations as "Tested" once a contributor confirms them. If you try one of the untested combinations and it works (or doesn't), please open an issue — it helps everyone.

For detailed per-client setup instructions, config file locations, and platform-specific notes, see the MCP Client Setup Guide.

Manual Install

Requires uv.

uv tool install "dm20-protocol @ git+https://github.com/Polloinfilzato/dm20-protocol.git"

Then add to your MCP client's config file (see MCP Client Setup Guide for your client's config path):

{
  "mcpServers": {
    "dm20-protocol": {
      "command": "dm20-protocol",
      "env": {
        "DM20_STORAGE_DIR": "/path/to/your/data"
      }
    }
  }
}

Note: Some clients (like Claude Desktop) don't inherit your shell PATH. Use the absolute path instead: "command": "/Users/you/.local/bin/dm20-protocol" (find it with which dm20-protocol).

On Linux, if dm20-protocol is not found after install, run uv tool update-shell or add ~/.local/bin to your PATH manually.

git clone https://github.com/Polloinfilzato/dm20-protocol.git
cd dm20-protocol
uv sync

Then add to your MCP client's config file (see MCP Client Setup Guide for your client's config path):

{
  "mcpServers": {
    "dm20-protocol": {
      "command": "uv",
      "args": ["run", "python", "-m", "dm20_protocol"],
      "cwd": "/absolute/path/to/dm20-protocol",
      "env": {
        "DM20_STORAGE_DIR": "/path/to/your/data"
      }
    }
  }
}

Note: Claude Desktop doesn't inherit your shell PATH. Use absolute paths for both command and cwd. Find uv with which uv.

Quick Start

Once your MCP client is configured, try these natural language commands to get started:

Create a new campaign called "The Lost Kingdom"

Load the D&D 5e rules: load_rulebook source=srd

Create a level 3 High Elf Wizard named Lyra with Standard Array

Create a location called "Silverdale", a peaceful village surrounded by ancient forests

Create an NPC named Marta, an elderly herbalist who lives in Silverdale

Create a quest called "The Missing Amulet" given by Marta

The AI will use DM20's tools automatically — no special syntax needed. Just describe what you want in plain English. With a rulebook loaded, the Character Builder auto-populates HP, proficiencies, features, equipment, and spell slots from official rules.

For the full list of 86 tools and advanced usage, see the User Guide. For a complete example campaign, see example/dnd/.

Playing the Game

Claude Code (recommended — full AI DM experience)

Claude Code includes slash commands that turn Claude into a complete Dungeon Master. Each command injects a detailed DM persona with situation-specific instructions and a dual-agent architecture (Narrator + Arbiter running in parallel).

/dm:start Curse of Strahd           ← start session (once)
/dm:action I explore the tavern      ← exploration, social, any non-combat action
/dm:action I talk to the innkeeper

/dm:combat Wolves burst from the woods!   ← starts combat
/dm:combat I attack with my longsword     ← each combat turn needs /dm:combat
/dm:combat I cast Shield as a reaction    ← still in combat
                                          ← combat ends automatically when enemies fall

/dm:action I search the wolf den     ← back to exploration after combat
/dm:save                             ← save and stop

Important: Use /dm:combat for every action during combat, not just to start it. /dm:action cannot advance combat turns — it's designed for exploration and social encounters only.

Other MCP Clients (Claude Desktop, Cursor, etc.)

Without Claude Code, use DM20's tools through natural language. Add the recommended system prompt to your client's system prompt field for the best experience — it includes the full game loop, combat protocol, and DM behavior guidelines.

The AI will chain tools automatically based on your requests. The experience is good, but slash commands provide more consistent results because they inject context-specific instructions on every message.

Optional: Smarter Rulebook Search

By default, when you search your PDF rulebooks with ask_books, the system uses keyword matching — it finds results that contain the exact words you typed. This works well for specific lookups like "fireball" or "fighter".

With RAG (Retrieval-Augmented Generation) enabled, the system understands meaning, not just words. For example:

To enable it, run this from inside Claude Code:

/dm:install-rag

This installs ChromaDB (~200 MB), a local vector database that runs entirely on your machine — no cloud services, no API keys. The command auto-detects your setup and handles platform quirks automatically.

uv sync --extra rag

Note: RAG is not available on macOS Intel (x86_64) due to missing ML library support. Everything else works perfectly without it — keyword search covers most use cases just fine.

Optional: Voice Narration

By default, DM20 narrates through text only. With voice enabled, the DM reads narration and NPC dialogue aloud in real time using text-to-speech (TTS) — no cloud subscriptions or API keys needed.

On Apple Silicon, DM20 uses a 3-tier engine system that picks the best engine for each context. Other platforms use Edge-TTS for all tiers:

First-use note (Apple Silicon): The Qwen3-TTS model downloads ~1.2 GB from Hugging Face on first narrated session. The --voice install step itself is only ~50 MB (packages). The model is then cached and never re-downloaded.

To add voice narration to an existing install:

bash <(curl -fsSL https://raw.githubusercontent.com/Polloinfilzato/dm20-protocol/main/install.sh) --voice

After installation, activate voice inside Claude Code with /dm:profile — it shows an interactive menu to set the interaction mode. Or set it directly:

configure_claudmaster interaction_mode="narrated"

Audio plays in your browser, not the terminal. Run /dm:party-mode, open the URL shown, and leave that tab playing. For LAN sessions (everyone at the same table), only one device should have audio on — mute the browser tab on player devices to avoid the same narration playing from multiple speakers simultaneously.

The complete voice setup walkthrough — interaction modes, 3-tier engine details, and LAN vs remote scenarios — is in the User Guide.

uv sync --extra voice

Development

git clone https://github.com/Polloinfilzato/dm20-protocol.git
cd dm20-protocol
uv sync --group dev

Run tests:

uv run pytest tests/

Run the server locally:

uv run python -m dm20_protocol

Solo Play — AI Dungeon Master

DM20 Protocol includes a complete AI Dungeon Master system for solo D&D play. Claude becomes your DM — narrating the world, roleplaying NPCs, running combat, and tracking all game state automatically.

Game Commands

How It Works

The system uses a dual-agent architecture where two specialized LLM agents run in parallel on every player action:

• Narrator — Rich scene descriptions, NPC dialogue, atmospheric text

• Arbiter — Mechanical resolution, dice rolls, rule adjudication

A DM Persona (.claude/dm-persona.md) orchestrates the game loop: gather context, decide what happens, execute via tools, update state, narrate the outcome. A Python-side Archivist agent handles data retrieval and game state tracking without consuming LLM tokens.

Model Profiles let you trade quality vs token cost with a single command. All profiles use Opus with different effort levels — medium effort matches Sonnet quality with ~76% fewer output tokens:

Switch mid-session with /dm:profile economy or via configure_claudmaster(model_profile="quality"). The profile updates both the Python-side config and the Claude Code agent files at once.

Interaction Modes control how the DM communicates with players. They are orthogonal to model profiles — any combination of mode × profile is valid (3 × 3 = 9 combos):

Set at campaign creation with create_campaign(interaction_mode="narrated") or switch mid-session via configure_claudmaster(interaction_mode="immersive"). Default is classic (text-only, no extra dependencies). Non-classic modes require pip install dm20-protocol[voice].

Note: Model profiles and effort levels are a Claude-specific feature. The effort parameter is only supported on Anthropic's Opus models via the Claude API. If you're using dm20-protocol with a different MCP client or LLM backend, the effort setting will have no effect — the system still works, but you won't get the quality/cost scaling that effort provides. CC agent file updates (.claude/agents/*.md) are specific to Claude Code.

Based on academic research showing multi-agent GM outperforms single-agent approaches. Built on the Claudmaster architecture with session persistence, difficulty scaling, and configurable narrative style.

See the Player Guide for how to play, or the Roadmap for what's next.

Documentation

• Player Guide — How to play solo D&D with the AI DM

• Party Mode — Multi-player web relay architecture and setup

• User Guide — System prompt, tools reference, data structure, PDF library

• Storage Structure — How campaign data is organized on disk

• Development Guide — Architecture, contributing, API details

• Roadmap — What's implemented, what's next

• Changelog — Version history

Credits

This project started as a fork of gamemaster-mcp by Joel Casimir, who created the initial foundation for D&D campaign management via MCP.

The project has since been extensively rewritten and expanded with 66 MCP tools, a multi-source rulebook system, a PDF library, the Claudmaster dual-agent AI DM, and comprehensive test coverage.

License

MIT License