Gamemaster MCP

🚀 Gamemaster MCP 🐉

Gamemaster MCP 🐉 is a comprehensive Model Context Protocol MCP server designed for managing AI - assisted Dungeons & Dragons campaigns. Built with FastMCP 2.9.0+, it aims to be the ultimate AI - assisted Dungeon Master for DnD 5e. It offers a comprehensive toolkit for groups to run campaigns more effectively, a complete virtual DnD experience for solo players, and powerful tools to assist worldbuilders in creating rich and interconnected game worlds.

🚧 Under construction 🚧

🚀 Quick Start

The Gamemaster MCP server is built on FastMCP, providing structured data models and intelligent tools for all aspects of a D&D campaign. It enables natural language interaction through MCP clients.

✨ Features

🌍 Campaign Management

This is the foundation of your D&D world. Each campaign includes:

• Core Metadata: Name, description, setting, and 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, and world conditions.

All data is automatically saved and can be shared between sessions. You can create and manage multiple campaigns, switch between them seamlessly, and track campaign metadata.

📑 Character Management

It provides complete D&D 5e character sheets with:

• Core Attributes: Ability scores with auto - calculated modifiers.
• Combat Stats: HP, AC, saving throws, and 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.

🧝 NPC Management

Bring your world to life with rich NPCs featuring descriptions, relationships, locations, secrets, and stats. NPCs can be linked to quests and locations for easy reference. You can create and track non - player characters, manage their relationships and locations, and store descriptions and notes.

🗺️ Location/World Building

Create immersive settings with detailed descriptions, notable features, connections, inhabitants, and lore. Locations update as the party explores. You can create detailed locations, track populations, governments, and notable features, and connect locations to manage geography.

💎 Quest Management

Track story arcs and missions with clear objectives, status tracking, givers & rewards, time sensitivity, and branching paths. Quest progress automatically updates the Game State and Adventure Log. You can create quests with objectives and rewards, track quest status and completion, and link quests to NPCs and locations.

⚔️ Combat Management

Track and run dynamic combat encounters with initiative order, turn tracking, condition management, damage/healing, and enemy stats. Combat data flows to character sheets, the Game State, and the Adventure Log. It includes initiative tracking, turn - based combat flow, and combat encounter planning.

⏰ Session Management

Organize your game sessions with session notes, attendance tracking, XP awards, loot distribution, and game date tracking. Session data updates character sheets, the Game State, and the Adventure Log. It includes session notes and summaries, experience and treasure tracking, and character attendance.

🏕️ Adventure Log

This is your campaign's living history, with event types, a timeline view, searchability, tags & importance, and session linking. The log connects to quests, locations, and NPCs. It offers comprehensive event logging, categorized by event type, searchable and filterable, with importance ratings.

🎮 Game State Tracking

It provides a snapshot of your world, including party status, active quests, world conditions, time tracking, and combat status. The Game State connects all other models, updates from character actions, drives world simulation, and informs AI DM decisions. It tracks the current location and session, party level and funds, combat status, and in - game date.

🎲 Utility Tools

It includes dice rolling with advantage/disadvantage, experience point calculations, and D&D 5e mechanics support.

📦 Installation

Prerequisites

• Python 3.12+
• uv (available in your system's PATH)

User Installation

1. Clone the repository:

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

2. Create a virtual environment and install dependencies:

   uv venv
   uv pip install .
   

💻 Usage Examples

Running the Server from the Command Line

First, activate the virtual environment:

# On macOS/Linux
source .venv/bin/activate

# On Windows
.venv\Scripts\activate

Then, run the executable:

gamemaster - mcp

Alternatively, use uv to run the script without activating the environment:

uv run gamemaster - mcp

Running with an MCP Client (e.g., Claude Desktop)

Configure your MCP client to use uv to run the server. Provide the path to your project folder as the working directory.

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

Note: Replace C:\\path\\to\\your\\gamemaster - mcp with the absolute path to the project directory.

📚 Documentation

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

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

Available Tools (25+ FastMCP Tools)

Campaign Management

• 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

Character Management

• 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

NPC Management

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

Location Management

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

Quest Management

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

Game State Management

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

Combat Management

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

Session Management

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

Adventure Log

• add_event - Add event to adventure log
• get_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

🔧 Technical Details

Data Structure

The Gamemaster MCP server organizes all campaign data around a central Campaign model, which is the primary container for the entire game world. This design ensures a cohesive and interconnected data structure, facilitating easy management and interaction with various game elements.

The system has a hierarchical data structure with the Campaign model at its core. All other models relate to the active campaign, as shown in the following mermaid graph:

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 in src/gamemaster_mcp/models.py interact:

• Campaign: The foundational model. It encapsulates all campaign - specific data, including characters, NPCs, locations, quests, encounters, sessions, and the game state.
• GameState: While part of the Campaign, it plays a pivotal role in reflecting the current state of the world. It influences and is influenced by other models.
• AdventureEvent: This model is used to log significant occurrences throughout the campaign. It often references elements from the Campaign's data, providing 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.

1. Follow steps from the User Installation to clone the repo and set up the virtual environment.
2. Install in editable mode with development dependencies:

uv pip install -e .[dev]

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:

uv run pytest

📄 License

MIT License