README.md
A comprehensive MCP server for managing AI-assisted Dungeons & Dragons campaigns
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:refrillsaves 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:
| User (recommended) | Developer | |
|---|---|---|
| Who it's for | Players who want to play D&D | Contributors who want to modify the code |
| What it installs | A single dm20-protocol command |
Full source code repository |
| Disk footprint | Minimal (~50 MB) | Full dev environment (~200+ |
Tools (3)
dm:startInitializes a new D&D campaign session.dm:helpDisplays available commands and help documentation for the DM20 protocol.dm:refrillSaves the current session and provides instructions to clear context for memory management.Configuration
claude_desktop_config.json
{"mcpServers": {"dm20-protocol": {"command": "npx", "args": ["-y", "dm20-protocol"]}}}Try it
→Start a new D&D campaign using the 2024 revised rules.
→Create a new character using the guided creation wizard.
→Add a new NPC to the current campaign and link them to the starting location.
→Initiate combat encounter with the current party and track initiative.
→Import my character from this D&D Beyond URL.