ddb-mcp

A TypeScript MCP server for D&D Beyond. It gives MCP-compatible clients access to your D&D Beyond characters, campaigns, and reference lookups.

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. Using it may violate D&D Beyond's terms of service.

Attribution

This project is based on dndbeyond-mcp by Alex Worland. The original README stated that work was MIT-licensed.

This repository continues that MCP server. It does not include personal vault-export or third-party stat-block backfill scripts from the original tree. Write tools are opt-in so an agent cannot mutate or delete characters unless you enable that mode.

Related MCP server: D&D Beyond MCP Server

Features

• Character reads — Character sheets by ID or name

• Campaign access — List campaigns and party rosters

• Reference lookups — Spells, monsters, items, feats, conditions, classes, races, backgrounds

• Optional session writes — HP, spell slots, rests, conditions, currency (off by default)

• Optional builder tools — Create/update/delete characters (off by default; delete requires confirmation)

• Browser-based auth — Playwright login flow; run it yourself, not through the agent

Prerequisites

• Node.js 20+ and npm

• git

• Google Chrome — the login flow launches real Chrome (not Playwright's bundled Chromium), so it needs to already be installed:

  • Debian/Ubuntu: download the .deb from google.com/chrome or add Google's apt repo

  • Fedora: sudo dnf install google-chrome-stable (after enabling Google's repo, or via the RPM from their site)

  • macOS: brew install --cask google-chrome

  • Windows: winget install Google.Chrome

If you're being walked through this by an AI coding agent, see CLAUDE.md — it has the exact command sequence for a fresh setup.

Installation

npx ddb-mcp

Or install globally:

npm install -g ddb-mcp

From a local checkout:

git clone https://github.com/Doogan1/ddb-mcp.git
cd ddb-mcp
npm install
npx playwright install chromium
npm run build

Setup

Authenticate with D&D Beyond from a terminal you control — this step is interactive and opens a real, visible browser window, so it can't be run through an agent's sandboxed shell or a headless server:

npx ddb-mcp setup

Log in normally in the browser window that opens. The session cookie is saved to ~/.dndbeyond-mcp/config.json. Do not share that file — see Securing your credentials below.

Once connected to an MCP client, verify the session with the check_auth tool.

Securing your credentials

~/.dndbeyond-mcp/config.json holds your D&D Beyond session cookie — anyone with read access to it has access to your D&D Beyond account. The directory isn't created with restrictive permissions by default, so lock it down after your first npm run setup:

chmod 700 ~/.dndbeyond-mcp
chmod 600 ~/.dndbeyond-mcp/config.json

Tool access modes

Write tools are not registered unless you set DDB_MCP_MODE. Default is read.

delete_character also requires confirm: true and the exact character name.

Claude Desktop / Cursor configuration

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

Read-only (recommended default):

{
  "mcpServers": {
    "dndbeyond": {
      "command": "npx",
      "args": ["-y", "ddb-mcp"],
      "env": {
        "DDB_MCP_MODE": "read"
      }
    }
  }
}

Session play (HP, spell slots, rests):

{
  "mcpServers": {
    "dndbeyond": {
      "command": "npx",
      "args": ["-y", "ddb-mcp"],
      "env": {
        "DDB_MCP_MODE": "session"
      }
    }
  }
}

From a local build, point command at node and args at build/src/index.js.

Restart the client after changing the config.

Claude Code configuration

From a local checkout, register the server with the Claude Code CLI instead of hand-editing a JSON file:

claude mcp add ddb-mcp -s user -e DDB_MCP_MODE=read -- node /absolute/path/to/ddb-mcp/build/src/index.js

• -s user registers it for every project, not just the current directory. Use -s local (the default) to scope it to one project instead.

• -e DDB_MCP_MODE=session (or builder) instead of read to enable write tools, same modes as above.

• The path after -- must be absolute and point at your own local build — node build/src/index.js alone only works if Claude Code's working directory happens to be this repo.

Verify it's connected:

claude mcp list
claude mcp get ddb-mcp

If this repo's own .mcp.json still points at someone else's absolute path (e.g. from cloning a fork), either fix that path to your own, or remove/ignore it if you're using -s user registration instead — a stale project-scoped entry and a user-scoped entry pointing at different paths will conflict.

Tools

Always available (read)

• check_auth — Verify the saved session

• get_character / list_characters / get_definition

• list_campaigns / get_campaign_characters

• search_spells / get_spell

• search_monsters / get_monster

• search_items / get_item

• search_feats / get_condition / search_classes

• search_races / search_backgrounds / search_class_features / search_racial_traits

Login is a CLI command (npm run setup), not an agent tool.

Session mode

• update_hp / set_inspiration / add_condition / remove_condition

• update_spell_slots / update_pact_magic / cast_spell

• update_death_saves / update_currency / use_ability

• long_rest / short_rest

Builder mode

• create_character / delete_character

• Class, species, background, ability scores, inventory, description, and choice tools

Resources

Prompts

Security

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

D&D Beyond may restrict unofficial clients. Prefer read mode. Do not bulk-export catalogs you do not own. Monster lookups honor D&D Beyond accessType flags; unowned stat blocks stay stubbed.

Troubleshooting

sudo: a terminal is required to read the password — if an AI agent is helping you install prerequisites, it can't supply your sudo password interactively. Run the install command yourself in your own terminal, then let the agent continue.

Playwright complains it can't find a browser — the bundled Chromium download is separate from npm install. Run:

npx playwright install chromium

The login browser window won't open, or npm run setup hangs — the login flow launches a real, visible browser window (headless: false), so it needs an actual display. It won't work over a plain SSH session without X forwarding, inside most containers, or through an agent's sandboxed shell. Run it directly in a terminal on a machine with a screen.

npm run setup fails immediately with a browser launch error — confirm real Google Chrome is installed (google-chrome --version or google-chrome-stable --version), not just Playwright's Chromium; see Prerequisites.

Claude Code shows the server as disconnected, or tools from a stale path — check for a conflict between this repo's own .mcp.json (project scope) and a -s user registration; see the note at the end of Claude Code configuration.

License

MIT. See LICENSE.