The D&D MCP Server is a comprehensive tool for managing AI-assisted Dungeons & Dragons campaigns, offering DMs a complete suite of campaign management tools:
- Campaign Management: Create, track, and switch between campaigns with metadata (name, description, DM, setting)
- Character Management: Create and update detailed D&D 5e character sheets including ability scores, combat stats, inventory, and spellcasting
- NPC Management: Create and track non-player characters with descriptions, relationships, locations, and attitudes
- Location/World Building: Create detailed locations with populations, governments, and notable features
- Quest Management: Track quests with objectives, status, rewards, and connections to NPCs/locations
- Combat Management: Run encounters with initiative tracking, turn management, and condition tracking
- Session Management: Log attendance, XP awards, loot distribution, and in-world time
- Adventure Log: Record and search historical campaign events by category
- Game State Tracking: Monitor current party status, location, active quests, and combat status
- Utility Tools: Roll dice with advantage/disadvantage and calculate XP distribution
Provides comprehensive tools for managing D&D 5e campaigns, including character sheets, NPCs, combat encounters, quests, locations, and game mechanics like dice rolling
Gamemaster MCP 🐉
A comprehensive Model Context Protocol MCP server for managing AI-assisted Dungeons & Dragons campaigns, built with FastMCP 2.9.0+
Gamemaster MCP 🐉 aims to be the ultimate AI-assisted Dungeon Master for DnD 5e, providing:
- For Groups: A comprehensive toolkit to help the user run campaigns more effectively
- For Solo Players: A complete virtual DnD experience that facilitates immersive solo play
- For Worldbuilders: Powerful tools to assist in creating rich, interconnected game worlds
Built on FastMCP, the server provides structured data models and intelligent tools to manage all aspects of a D&D campaign while enabling natural language interaction through MCP clients.
🚧 Under construction 🚧
✨ Features
🌍 Campaign Management
The foundation of your D&D world. Each campaign contains:
- Core Metadata: Name, description, setting, DM name
- Characters: All player characters and their sheets
- NPCs: Every non-player character in your world
- Locations: Cities, dungeons, and points of interest
- Quests: Active and completed storylines
- Game State: Current session, party location, world conditions
All data is automatically saved and can be shared between sessions.
- Create and manage multiple campaigns
- Switch between campaigns seamlessly
- Track campaign metadata (name, description, DM, setting)
📑 Character Management
Complete D&D 5e character sheets with:
- Core Attributes: Ability scores with auto-calculated modifiers
- Combat Stats: HP, AC, saving throws, resistances
- Inventory: Equipment with weight and value tracking
- Spellcasting: Prepared spells, slots, and DCs
- Progression: Level ups with automatic feature unlocks
Characters evolve as you play - taking damage, gaining items, and leveling up.
- Complete character sheets with D&D 5e stats
- Ability scores with automatic modifier calculation
- Hit points, armor class, and combat stats
- Inventory and equipment management
- Spellcasting support
🧝 NPC Management
Bring your world to life with rich NPCs featuring:
- Descriptions: Appearance, personality, voice notes
- Relationships: Connections to other characters/factions
- Locations: Where they live and frequent
- Secrets: Hidden motivations and knowledge
- Stats: Quick reference for combat if needed
NPCs can be linked to quests and locations for easy reference.
- Create and track non-player characters
- Manage relationships and locations
- Store descriptions and notes
🗺️ Location/World Building
Create immersive settings with:
- Detailed Descriptions: Sensory details and maps
- Notable Features: Landmarks, secrets, hazards
- Connections: Linked areas for travel routes
- Inhabitants: NPCs and monsters present
- Lore: Local history and legends
Locations update as the party explores - adding discovered areas and changing conditions.
- Create detailed locations (cities, dungeons, etc.)
- Track populations, governments, and notable features
- Connect locations and manage geography
💎 Quest Management
Track story arcs and missions with:
- Objectives: Clear steps to completion
- Status Tracking: Active/Completed/Failed
- Givers & Rewards: Connected NPCs and prizes
- Time Sensitivity: Optional deadlines
- Branching Paths: Alternate resolutions
Quest progress automatically updates the Game State and Adventure Log.
- Create quests with objectives and rewards
- Track quest status and completion
- Link quests to NPCs and locations
⚔️ Combat Management
Track and run dynamic combat encounters with:
- Initiative Order: Automatic sorting with manual override
- Turn Tracking: Current actor highlight and turn reminders
- Condition Management: Status effects with duration tracking
- Damage/Healing: Apply with automatic HP calculation
- Enemy Stats: Quick reference for monsters/NPCs
Combat data flows to:
- Character sheets (HP, conditions)
- Game State (current encounter)
- Adventure Log (combat events)
- Initiative tracking
- Turn-based combat flow
- Combat encounter planning
⏰ Session Management
Organize your game sessions with:
- Session Notes: Key events and decisions
- Attendance Tracking: Which players were present
- XP Awards: Track character progression
- Loot Distribution: Treasure found and claimed
- Game Date: Track in-world time passage
Session data updates:
- Character sheets (XP, items)
- Game State (current session #)
- Adventure Log (session summary)
- Session notes and summaries
- Experience and treasure tracking
- Character attendance
🏕️ Adventure Log
Your campaign's living history:
- Event Types: Combat, Roleplay, Exploration, etc.
- Timeline View: Chronological story progression
- Searchable: Find key moments quickly
- Tags & Importance: Highlight major plot points
- Session Linking: Connect events to game sessions
The log connects to:
- Quests (progress updates)
- Locations (where events occurred)
- NPCs (who was involved)
- Comprehensive event logging
- Categorized by event type (combat, roleplay, exploration, etc.)
- Searchable and filterable
- Importance ratings
🎮 Game State Tracking
The current snapshot of your world:
- Party Status: Location, resources, conditions
- Active Quests: Current objectives and progress
- World Conditions: Weather, political climate
- Time Tracking: In-game date and time
- Combat Status: Current encounter details
The Game State connects all other models:
- Updates from character actions
- Drives world simulation
- Informs AI DM decisions
- Current location and session
- Party level and funds
- Combat status
- In-game date tracking
🎲 Utility Tools
- Dice rolling with advantage/disadvantage
- Experience point calculations
- D&D 5e mechanics support
💾 Installation
Prerequisites
- Python 3.12+
uv
(available in your system's PATH)
User Installation
- Clone the repository:
- Create a virtual environment and install dependencies:
🏁 Running the Server
From the Command Line
To run the server directly, first activate the virtual environment:
Then, run the executable:
Alternatively, use uv
to run the script without activating the environment:
With an MCP Client (e.g., Claude Desktop)
Configure your MCP client to use uv
to run the server. You only need to provide the path to your project folder as the working directory.
Note: Replace C:\\path\\to\\your\\gamemaster-mcp
with the absolute path to the project directory.
🎛️ System Prompt Recommendation
For optimal performance, use a system prompt that primes the LLM to act as a knowledgeable Dungeon Master's assistant. This prompt should guide the model to understand the context of D&D campaign management and leverage the provided tools effectively.
📜 Example System Prompt
Available Tools (25+ FastMCP Tools)
Campaign Management
create_campaign
- Create a new campaignget_campaign_info
- Get current campaign informationlist_campaigns
- List all available campaignsload_campaign
- Switch to a different campaign
Character Management
create_character
- Create a new player characterget_character
- Get character sheet detailsupdate_character
- Update a character's properties (name, stats, HP, etc.).bulk_update_characters
- Update multiple characters at once (e.g., apply damage to all).add_item_to_character
- Add items to inventorylist_characters
- List all characters
NPC Management
create_npc
- Create a new NPCget_npc
- Get NPC detailslist_npcs
- List all NPCs
Location Management
create_location
- Create a new locationget_location
- Get location detailslist_locations
- List all locations
Quest Management
create_quest
- Create a new questupdate_quest
- Update quest status or objectiveslist_quests
- List quests (optionally filtered by status)
Game State Management
update_game_state
- Update current game stateget_game_state
- Get current game state
Combat Management
start_combat
- Initialize combat with initiative orderend_combat
- End combat encounternext_turn
- Advance to next participant's turn
Session Management
add_session_note
- Add session notes and summaryget_sessions
- Get all session notes
Adventure Log
add_event
- Add event to adventure logget_events
- Get events (with filtering and search)
Utility Tools
roll_dice
- Roll dice with D&D notation (e.g., "1d20", "3d6+2")calculate_experience
- Calculate XP distribution for encounters
💽 Data Structure
The Gamemaster MCP server organizes all campaign data around a central Campaign
model, which acts as the primary container for the entire game world. This design ensures a cohesive and interconnected data structure, allowing for easy management and interaction with various game elements.
The system is built around a hierarchical data structure with the Campaign
model at its core. All other models relate to the active campaign, as shown below:
Here's how the core data models in src/gamemaster_mcp/models.py
interact:
Campaign
: The foundational model. It encapsulates all campaign-specific data, including:characters
: A dictionary ofCharacter
models, representing player characters. EachCharacter
is a complex model composed ofCharacterClass
,Race
,AbilityScore
(for core stats),Item
(for inventory and equipment), andSpell
(for known spells).npcs
: A dictionary ofNPC
models, representing non-player characters. NPCs can be linked toLocation
models.locations
: A dictionary ofLocation
models, defining places within the campaign world. Locations can list associated NPCs and connections to other locations.quests
: A dictionary ofQuest
models, tracking ongoing and completed missions. Quests can reference NPCs as givers.encounters
: A dictionary ofCombatEncounter
models, detailing planned or active combat scenarios. Encounters can be tied to specific locations.sessions
: A list ofSessionNote
models, providing summaries and details for each game session played within the campaign.game_state
: A singleGameState
model, which captures the dynamic, real-time conditions of the campaign, such as the current location, active quests, and party funds. This model is crucial for understanding the immediate context of the game.
GameState
: While part of theCampaign
,GameState
plays a pivotal role in reflecting the current state of the world. It influences and is influenced by other models:current_location
can point to aLocation
model.active_quests
referencesQuest
titles.- Changes in
Character
status (e.g.,hit_points_current
) orQuest
status (active
,completed
) directly impact theGameState
.
AdventureEvent
: This model is used to log significant occurrences throughout the campaign. While not directly nested withinCampaign
(it's stored globally),AdventureEvent
instances often reference elements from theCampaign
's data, such ascharacters_involved
andlocation
. This provides a historical log for understanding past events and narrative progression.
🖥️ Development
Development Workflow
If you want to contribute to the project, the setup is slightly different.
- Follow steps from the User Installation to clone the repo and set up the virtual environment.
- Install in editable mode with development dependencies:This installs the project in a way that your code changes are immediately reflected without needing to reinstall. It also installs tools for testing and linting.
Running Tests
To run the test suite, use the following command:
📜 License
MIT License
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
A comprehensive Model Context Protocol server for managing Dungeons & Dragons campaigns with tools for characters, NPCs, locations, quests, combat encounters, and session tracking.
Related MCP Servers
- AsecurityAlicenseAqualityA beginner-friendly Model Context Protocol (MCP) server that helps users understand MCP concepts, provides interactive examples, and lists available MCP servers. This server is designed to be a helpful companion for developers working with MCP. Also comes with a huge list of servers you can install.Last updated -3936JavaScriptApache 2.0
- -securityFlicense-qualityModel Context Protocol server that enables LLMs and AI assistants to retrieve real-time Dota 2 statistics, match data, player information, and game metrics through a standardized interface.Last updated -4Python
- -securityFlicense-qualityA Model Context Protocol server that provides tools for interacting with databases, including PostgreSQL, DuckDB, and Google Cloud Storage Parquet files.Last updated -2TypeScript
- -securityAlicense-qualityA server that implements the Model Context Protocol, providing a standardized way to connect AI models to different data sources and tools.Last updated -35TypeScriptMIT License