Gamemaster

Gamemaster MCP is a dedicated server for managing AI-assisted Dungeons & Dragons campaigns. It provides structured data models for campaigns, characters, NPCs, locations, quests, and game state, plus practical tools to run, track, and narrate your adventures with an MCP client. It’s designed to help DMs and players collaborate, automate routine tasks, and keep a rich, searchable history of your campaign.

How to use

You interact with Gamemaster MCP through an MCP client, connecting to a local or remote server and issuing structured actions to manage campaigns, characters, locations, quests, encounters, and the game state. Start by selecting or loading a campaign, then create or edit entities as your story unfolds. Use the Adventure Log to record events, and the Game State to keep track of the party’s current situation. All data is organized around a central Campaign model, ensuring everything stays consistent and easy to reference during play.

Plan your sessions by updating session notes, tracking XP, loot, and attendance, and logging key moments as they happen. When combat or exploration occurs, use the combat and quest tools to reflect outcomes, update HP or statuses, and drive narrative progression. The system is designed to support interactive storytelling, so you can chain tool actions to achieve complex results—like creating a quest, assigning an NPC as the quest giver, and tying that quest to a location.

To get started, ensure your client is configured to connect to the Gamemaster MCP server, then begin with creating a campaign or loading an existing one. From there, build your party, flesh out your world, and launch your adventure with a structured workflow that keeps data in sync across characters, NPCs, quests, locations, and game state.

How to install

Prerequisites: Python 3.12 or newer, and uv available in your system PATH.

User installation steps:

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

uv venv
uv pip install .

Running the server

Activate the virtual environment, then run the server directly. You can also use uv to run the script without manual activation.

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

# On Windows
.venv\Scripts\activate

gamemaster-mcp

uv run gamemaster-mcp

Configure an MCP client

If you’re using an MCP client to manage the server, point the client at the local or remote process using the provided command. The following example shows a local setup where uv runs the server from your project folder.

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

System prompt and in-play guidance

For best results, use a system prompt that primes the AI to act as a knowledgeable Dungeon Master assistant. The prompt should emphasize campaign-centric data handling, structured data models, and proactive, narrative-driven tool use to support the ongoing story.

Notes on ongoing use

As play unfolds, keep the Game State updated with location, active quests, and combat status. Log important events to the Adventure Log, and update character and NPC statuses as needed. Refer back to prior events to maintain narrative continuity and ensure a cohesive campaign experience.

Troubleshooting tips

If the server fails to start, verify Python 3.12+ is installed and that uv is available in your PATH. Ensure you activate the virtual environment before starting the server, or run it with uv as shown in the examples.

Available tools

create_campaign

Create a new campaign with core metadata and initial data.

get_campaign_info

Retrieve information about the currently loaded campaign.

list_campaigns

List all available campaigns.

load_campaign

Switch to a different campaign by name or ID.

create_character

Create a new player character with core stats and equipment.

get_character

Get full character sheet details.

update_character

Update character properties such as name, stats, or HP.

bulk_update_characters

Apply updates to multiple characters at once (e.g., apply damage).

add_item_to_character

Add an item to a character's inventory.

list_characters

List all characters in the current campaign.

create_npc

Create a new non-player character with descriptions and relationships.

get_npc

Get details for a specific NPC.

list_npcs

List all NPCs in the campaign.

create_location

Create a new location with descriptions and connections.

get_location

Get location details and linked entities.

list_locations

List all locations in the campaign.

create_quest

Create a new quest with objectives and rewards.

update_quest

Update quest status or objectives.

list_quests

List quests, optionally filtered by status.

start_combat

Initialize a combat encounter with initiative order.

end_combat

End the current combat encounter.

next_turn

Advance to the next participant in combat.

update_game_state

Update the current game state, including location and active quests.

get_game_state

Retrieve the current game state.

add_session_note

Add a session note with summaries and decisions.

get_sessions

Get all session notes.

add_event

Add an event to the Adventure Log.

get_events

Query events from the Adventure Log.

roll_dice

Roll dice using D&D notation (e.g., 1d20, 3d6+2).

calculate_experience

Calculate XP distribution for encounters.