D&D MCP Server

A comprehensiveModel Context Protocol MCPserver for managing AI-assisted Dungeons & Dragons campaigns, built withFastMCP 2.9.0+

git clone https://github.com/study-flamingo/gamemaster-mcp.git cd gamemaster-mcp

# On macOS/Linux source .venv/bin/activate # On Windows .venv\Scripts\activate

{ "mcpServers": { "gamemaster-mcp": { "command": "uv", "args": [ "run", "gamemaster-mcp" ], "cwd": "C:\\path\\to\\your\\gamemaster-mcp" } } }

Note: ReplaceC:\\path\\to\\your\\gamemaster-mcpwith the absolute path to the project directory.

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.

You are a master Dungeon Master (DM) or a Dungeon Master's Assistant, powered by the Gamemaster MCP server. Your primary role is to help users manage all aspects of their Dungeons & Dragons campaigns using a rich set of specialized tools. You are a stateful entity, always operating on a single, currently active campaign. Core Principles: 1. Campaign-Centric: All data—characters, NPCs, quests, locations—is stored within a single, active Campaign. Always be aware of the current campaign context. If a user's request seems to reference a different campaign, use the list_campaigns and load_campaign tools to switch context. 2. Structured Data: You are working with structured data models (Character, NPC, Quest, Location, etc.). When creating or updating these entities, strive to populate them with as much detail as possible. If a user is vague, ask for specifics (e.g., "What is the character's class and race? What are their ability scores?"). 3. Proactive Assistance: Don't just execute single commands. Fulfill complex user requests by chaining tools together. For example, to "add a new character to the party," you should use create_character, then perhaps add_item_to_character to give them starting gear. 4. Information Gathering: Before acting, use list_ and get_ tools to understand the current state. For instance, before adding a quest, you might list_npcs to see who could be the quest giver. 5. State Management: Use the get_game_state and update_game_state tools to keep track of the party's current location, in-game date, and combat status. 6. Be a Storyteller: While your primary function is data management, frame your responses in the context of a D&D game. You are not just a database; you are the keeper of the campaign's world. Interactive Session Zero: When a user wants to start a new campaign, initiate an interactive "Session Zero." Guide them through the setup process step-by-step, asking questions and using tools to build the world collaboratively. Use the following framework as a loose framework: it is more important to follow the user's prompting. However, be sure to establish the necessary parameters for each tool call. 1. Establish the Campaign:  You: "Welcome to the world of adventure! What shall we name our new campaign?" (Wait for user input)  You: "Excellent! And what is the central theme or description of 'Campaign Name'?" (Wait for user input)  Then, use create_campaign with the gathered information. 2. Build the Party:  You: "Now, let's assemble our heroes. How many players will be in the party?"  For each player, engage in a dialogue to create their character:  You: "Let's create the first character. What is their name, race, and class?"  You: "Great. What are their ability scores (Strength, Dexterity, etc.)?"  Use create_character after gathering the core details for each hero. 3. Flesh out the World:  You: "Where does our story begin? Describe the starting town or location."  Use create_location.  You: "Who is the first person the party meets? Let's create an NPC."  Use create_npc. 4. Launch the Adventure:  You: "With our world set up, what is the first challenge or quest the party will face?"  Use create_quest.  You: "Session Zero is complete! I've logged the start of your first session. Are you ready to begin?"  Use add_session_note. Your goal is to be an indispensable partner to the Dungeon Master, co-creating the campaign's foundation so they can focus on telling a great story. In-Play Campaign Guidance: Once the campaign is underway, your focus shifts to dynamic management and narrative support: 1. Dynamic World: Respond to player actions and tool outputs by dynamically updating the GameState, NPC statuses, Location details, and Quest progress. 2. Event Logging: Every significant interaction, combat round, roleplaying encounter, or quest milestone should be logged using add_event to maintain a comprehensive AdventureLog. 3. Proactive DM Support: Anticipate the DM's needs. If a character takes damage, suggest update_character_hp. If they enter a new area, offer get_location details. 4. Narrative Cohesion: Maintain narrative consistency. Reference past events from the AdventureLog or SessionNotes to enrich descriptions and ensure continuity. 5. Challenge and Consequence: When players attempt actions, consider the potential outcomes and use appropriate tools to reflect success, failure, or partial success, including updating character stats or game state. 6. Tool-Driven Responses: Frame your narrative responses around the successful execution of tools. For example, instead of "The character's HP is now 15," say "You successfully heal [Character Name], their hit points now stand at 15."

- create_campaign- Create a new campaign
- get_campaign_info- Get current campaign information
- list_campaigns- List all available campaigns
- load_campaign- Switch to a different campaign

- create_character- Create a new player character
- get_character- Get character sheet details
- update_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 inventory
- list_characters- List all characters

- create_npc- Create a new NPC
- get_npc- Get NPC details
- list_npcs- List all NPCs

- create_location- Create a new location
- get_location- Get location details
- list_locations- List all locations

- create_quest- Create a new quest
- update_quest- Update quest status or objectives
- list_quests- List quests (optionally filtered by status)

- update_game_state- Update current game state
- get_game_state- Get current game state

- start_combat- Initialize combat with initiative order
- end_combat- End combat encounter
- next_turn- Advance to next participant's turn

- add_session_note- Add session notes and summary
- get_sessions- Get all session notes

- add_event- Add event to adventure log
- get_events- Get events (with filtering and search)

- roll_dice- Roll dice with D&D notation (e.g., "1d20", "3d6+2")
- calculate_experience- Calculate XP distribution for encounters

The Gamemaster MCP server organizes all campaign data around a centralCampaignmodel, 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 theCampaignmodel at its core. All other models relate to the active campaign, as shown below:

graph TD A[Campaign] --> B[GameState] A --> C[Character] A --> D[NPC] A --> E[Location] A --> F[Quest] A --> G[CombatEncounter] A --> H[SessionNote] B --> I[AdventureEvent] C --> J[Item] C --> K[Spell] C --> L[AbilityScore] C --> M[CharacterClass] C --> N[Race] style A fill:#f9f,stroke:#333,stroke-width:4px

Here's how the core data models insrc/gamemaster_mcp/models.pyinteract:

-

Campaign: The foundational model. It encapsulates all campaign-specific data, including:

- characters: A dictionary ofCharactermodels, representing player characters. EachCharacteris a complex model composed ofCharacterClass,Race,AbilityScore(for core stats),Item(for inventory and equipment), andSpell(for known spells).
- npcs: A dictionary ofNPCmodels, representing non-player characters. NPCs can be linked toLocationmodels.
- locations: A dictionary ofLocationmodels, defining places within the campaign world. Locations can list associated NPCs and connections to other locations.
- quests: A dictionary ofQuestmodels, tracking ongoing and completed missions. Quests can reference NPCs as givers.
- encounters: A dictionary ofCombatEncountermodels, detailing planned or active combat scenarios. Encounters can be tied to specific locations.
- sessions: A list ofSessionNotemodels, providing summaries and details for each game session played within the campaign.
- game_state: A singleGameStatemodel, 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,GameStateplays a pivotal role in reflecting the current state of the world. It influences and is influenced by other models:

- current_locationcan point to aLocationmodel.
- active_questsreferencesQuesttitles.
- Changes inCharacterstatus (e.g.,hit_points_current) orQueststatus (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),AdventureEventinstances often reference elements from theCampaign's data, such ascharacters_involvedandlocation. This provides a historical log for understanding past events and narrative progression.

If you want to contribute to the project, the setup is slightly different.
-

Follow steps from the User Installationto 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.

To run the test suite, use the following command:

Publish, update, and manage Markdown pages on a permanent shareable URL directly from your AI conversation.

Publish HTML, Markdown, KV, JSON, files to brewpage.app from AI assistants.

Carryo is a remote MCP server for sharing Claude or ChatGPT-created HTML artifacts as live links.

An MCP server for viewing, editing, and creating text files, based on the Claude built-in text editor tool.

MCP server that reads and writes the system clipboard — tables, text, code, JSON, URLs, images, and more. Preserves spreadsheet structure (rows/columns) that is lost when pasting into Claude directly. Claude can also write results back to your clipboard.

A server for processing PDF files, allowing text and table extraction, metadata retrieval, and file listing within a specific directory.

An MCP server for interacting with Dropbox files and services.

Read and edit Word (.docx) documents with track changes, comments, footnotes, and structural validation. 18 tools with OOXML-level paraId validation and document auditing.

A read-only MCP server by CData that allows LLMs to query live Dropbox data. Requires the CData JDBC Driver for Dropbox.