D&D Beyond MCP

A local Model Context Protocol server that gives Claude access to D&D Beyond character sheets, an SRD content search, a dice roller, and (optionally) your campaigns.

Heads up: D&D Beyond has no official public API. The character and campaign tools use undocumented internal endpoints that Wizards of the Coast can change or remove without notice. The spell/monster/item search uses the open-licensed Open5e SRD API, which is stable. Keep usage personal and within D&D Beyond's terms of service.

Tools

Tool	What it does	Needs auth?
get_character	Fetch a public character sheet by ID (stats, HP, inventory, spells)	No
roll_dice	Roll standard notation: 2d6+3, 4d6, adv d20+5, dis d20	No
search_spells	Search SRD spells	No
search_monsters	Search SRD monster statblocks	No
search_magic_items	Search SRD magic items	No
list_campaigns	List campaigns on your account	Yes (cobalt cookie)
get_campaign	Details for one campaign	Yes (cobalt cookie)

The character tool only works if the sheet's privacy is set to Public (or Campaign Only) on D&D Beyond. Find the character ID in the sheet URL: dndbeyond.com/characters/<ID>.

Setup

1. Install Python 3.10+ and the dependencies:

   cd dndbeyond-mcp
   python3 -m pip install -r requirements.txt
   

2. Test that it starts (Ctrl+C to stop — it waits for a client over stdio):

   python3 server.py
   

Testing

A smoke test verifies tool registration, the dice roller (offline), the SRD search (live), and optionally a real character sheet:

python tests/test_smoke.py

To also test a public character sheet, pass its ID (from a dndbeyond.com/characters/<ID> URL):

python tests/test_smoke.py --character 24998307

Offline checks always run; the live SRD search is reported as SKIP (not a failure) if you have no network. A clean run ends with smoke test passed.

Connect to Claude Desktop

Edit your Claude Desktop config file:

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

Add this server (use the absolute path to server.py, and your real python3 path if needed):

{
  "mcpServers": {
    "dndbeyond": {
      "command": "python3",
      "args": ["/Users/seansanve/dndbeyond-mcp/server.py"],
      "env": {
        "DDB_COBALT_COOKIE": ""
      }
    }
  }
}

Replace the path above with wherever this folder lives on your machine. If you use a virtualenv, point command at that venv's python (e.g. /Users/seansanve/dndbeyond-mcp/.venv/bin/python) so the mcp and httpx dependencies are available.

Restart Claude Desktop. You should see the dndbeyond tools appear. Try:

• "Roll adv d20+7 for me."
• "Look up the fireball spell."
• "Fetch D&D Beyond character 12345678."

Enabling the campaign tools (optional)

list_campaigns and get_campaign need your login session:

1. Log in to dndbeyond.com in your browser.
2. Open DevTools (F12) → Application → Cookies → https://www.dndbeyond.com.
3. Copy the value of the CobaltSession cookie.
4. Paste it as DDB_COBALT_COOKIE in the config env above (or in a local .env file — see .env.example).

This cookie is a login secret — keep it private. It expires periodically; when the campaign tools start failing with auth errors, refresh it.

Notes & limitations

• Undocumented endpoints break sometimes. If get_character or the campaign tools return unexpected errors, the endpoints may have changed — check D&D Beyond's network traffic in DevTools to find the current URL and update server.py.
• get_character returns a readable summary by default; pass raw=true for the full JSON.
• The campaign endpoints (/api/campaign/stt/...) are best-effort and the least stable part of this server; they may need adjusting for your account.
• SRD search only covers open-licensed content, not paid D&D Beyond sourcebooks.