dndbeyond-mcp

A TypeScript MCP (Model Context Protocol) server for D&D Beyond. Gives Claude (and other MCP-compatible AI assistants) access to your D&D Beyond characters, campaigns, spells, monsters, items, and more.

Disclaimer: This project uses unofficial, reverse-engineered D&D Beyond endpoints. It is not affiliated with, endorsed by, or supported by D&D Beyond or Wizards of the Coast. Endpoints may change without notice.

Features

• Character Management — Read character sheets, update HP, spell slots, death saves, currency
• Campaign Access — List campaigns, view party rosters
• Reference Lookups — Search and retrieve spells, monsters, magic items, feats, conditions, classes
• Workflow Prompts — Session prep, encounter building, level-up guidance, spell recommendations
• Browser-Based Auth — Playwright-powered login flow (no manual cookie extraction)

Installation

You can run this server without installing via npx:

npx dndbeyond-mcp

Or install globally:

npm install -g dndbeyond-mcp

Setup

Before using the server, authenticate with D&D Beyond:

npx dndbeyond-mcp setup

This opens a browser window where you log into D&D Beyond normally. The server captures your session cookie automatically and saves it to ~/.dndbeyond-mcp/config.json.

By default the login flow launches your installed Chrome. To use a specific browser binary (e.g. on NixOS), set DNDBEYOND_MCP_BROWSER_PATH to its path:

DNDBEYOND_MCP_BROWSER_PATH=/run/current-system/sw/bin/chromium npx dndbeyond-mcp setup

Claude Desktop Configuration

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "dndbeyond": {
      "command": "npx",
      "args": ["-y", "dndbeyond-mcp"]
    }
  }
}

After adding the configuration, restart Claude Desktop.

Tools

Character

• get_character — Full character sheet by ID or name
• get_character_choices — Inspect builder choices: resolved values, options, and the ids to change them
• list_characters — All your characters
• update_hp — Apply damage or healing
• update_spell_slots — Use or restore spell slots
• update_death_saves — Record death saves
• update_currency — Modify gold/silver/copper
• use_ability — Decrement limited-use features

Campaign

• list_campaigns — Your active campaigns
• get_campaign_characters — All characters in a campaign

Reference

• search_spells / get_spell — Spell lookup with filters
• search_monsters / get_monster — Monster stat blocks
• search_items / get_item — Magic item catalog
• search_feats — Feat discovery
• get_condition — Condition rules
• search_classes — Class/subclass info

Utility

• setup_auth — Re-run login flow
• check_auth — Verify session is valid

Resources

URI	Description
dndbeyond://characters	Your character list
dndbeyond://character/{id}	Character sheet
dndbeyond://character/{id}/spells	Spell list
dndbeyond://character/{id}/inventory	Inventory
dndbeyond://campaigns	Your campaigns
dndbeyond://campaign/{id}/party	Party roster

Prompts

Prompt	Purpose
character-summary	Full character rundown
session-prep	DM session preparation
encounter-builder	Balanced encounter design
spell-advisor	Spell recommendations
level-up-guide	Level-up walkthrough
rules-lookup	Rules clarification

Security

This server stores your D&D Beyond session cookie locally at ~/.dndbeyond-mcp/config.json. The cookie provides full access to your D&D Beyond account. Never share this file. The server only communicates with dndbeyond.com domains.

Credits

Originally created by Alex Worland (@AlexWorland) — original repository: https://github.com/AlexWorland/dndbeyond-mcp

This fork, maintained by Dennis Konrad, adds to the character builder:

• Entity IDs in search_races / search_classes / search_backgrounds / search_feats / search_items output (required by the write tools)
• New tools: search_subclasses, set_max_hp, add_custom_proficiency, add_custom_item, equip_item
• Fixed update_currency (the deprecated endpoint was replaced with the working one)
• Corrected set_ability_score docs (base vs. bonus vs. override) and a resolve_choices caveat
• Test fixes after the character-list / race-shape refactor

License

MIT — see LICENSE.