Which integrations are available for this server?

Provides a comprehensive toolkit for managing D\&D 5e campaigns, including tools for character sheets, inventory, spellcasting, NPC and world-building, quest tracking, and a full combat system.

How do I use DM20 Protocol?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@DM20 Protocol Roll initiative for combat and show my character's current HP and spells" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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 Sheets — Full D&D 5e stats, inventory, spellcasting, progression
NPCs & Locations — Rich world-building with relationships and connections
Quest Tracking — Objectives, status, rewards, and branching paths
Combat System — Initiative, turns, conditions, damage/healing
Session Notes — Per-session summaries, XP, loot, attendance
Adventure Log — Searchable timeline of all campaign events
Dice & Utilities — Rolls, XP calculations, rules lookup
PDF Rulebook Library — Import and query your own PDFs and homebrew content
50+ MCP Tools — Full list in the User Guide

Prerequisites

Requirement	Version	Check	Install
Python	3.12+	`python3 --version`	python.org
uv	latest	`uv --version`	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
git	any	`git --version`	`xcode-select --install` (macOS)

Installation

This server implements the open Model Context Protocol standard. It works with any MCP-compatible client — not just Claude. If your AI tool supports MCP, it can run this server.

Tested with: Claude Desktop, Claude Code, Cursor, VS Code (Copilot), Windsurf, Cline, OpenAI Codex, Gemini CLI.

Quick Install

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

The interactive installer handles cloning, dependencies, MCP client configuration, and data directory setup. It detects your CPU architecture and warns about platform-specific limitations.

Manual Install

Clone and install dependencies (same for all clients):

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

Then configure your client:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Important: Claude Desktop does not inherit your shell PATH. Use the absolute path to uv (find it with which uv).

Add to ~/.claude/mcp.json (global) or .mcp.json (project-level):

{ "mcpServers": { "dm20-protocol": { "type": "stdio", "command": "uv", "args": ["run", "dm20-protocol"], "cwd": "/path/to/dm20-protocol", "env": { "DM20_STORAGE_DIR": "/path/to/your/data" } } } }

These editors have built-in MCP support. Add the server through their MCP settings UI, or edit the config file directly:

Cursor: ~/.cursor/mcp.json
Windsurf: ~/.codeium/windsurf/mcp_config.json
Cline: VS Code settings → Cline → MCP Servers

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

Add to your VS Code settings.json or .vscode/mcp.json:

{ "mcp": { "servers": { "dm20-protocol": { "command": "uv", "args": ["run", "dm20-protocol"], "cwd": "/path/to/dm20-protocol", "env": { "DM20_STORAGE_DIR": "/path/to/your/data" } } } } }

Requires Copilot Chat in Agent Mode (VS Code 1.99+).

Any MCP-compatible client can use this server. The key configuration:

Command: uv run dm20-protocol
Working directory: The cloned repository root
Environment: DM20_STORAGE_DIR — path where campaign data is stored (defaults to ./data)

Refer to your client's documentation for where to add MCP server entries. The transport is stdio (the default for most clients).

Optional: RAG Dependencies

For semantic search capabilities (vector-based library queries via ask_books):

uv sync --extra rag

Note: RAG dependencies (chromadb, onnxruntime) are not available on macOS Intel (x86_64). The server works fine without them — only the ask_books tool requires RAG. All other library tools use keyword search.

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 dm20-protocol

Roadmap

The next major feature is Claudmaster — an autonomous AI Dungeon Master powered by a multi-agent architecture:

Narrator Agent — Scene descriptions, NPC dialogue, atmosphere
Archivist Agent — Game state, rules lookup, combat management
Module Keeper Agent — RAG-based adventure module content
Consistency Engine — Fact tracking, contradiction detection

Play published adventures (Curse of Strahd, Lost Mines of Phandelver, etc.) with AI following the module plot while adapting to player choices. Supports solo play, group play, and DM assistant modes.

Based on academic research showing multi-agent GM outperforms single-agent approaches.

Status: In development.

Documentation

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
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.

Component	Origin	Lines
Original code (v0.1.0 foundation)	Joel Casimir	~3.9%
New code (library system, claudmaster, tools, tests)	DM20 Protocol contributors	~96.1%

The project has since been extensively rewritten and expanded with 50+ new tools, a PDF rulebook library system, the Claudmaster multi-agent architecture, and comprehensive test coverage.