Skip to main content
Glama

D&D Beyond MCP Server

A Model Context Protocol (MCP) server that gives Claude (or ChatGPT) direct access to your D&D Beyond account — characters, campaigns, sourcebooks, spells, monsters, rules, encounter planning, treasure generation, and more.

What's new — see the latest release notes.


For Players

Use Claude as a session companion that knows your character as well as you do.

Know your character inside out

Give me a full summary of my character Torvin
What spells do I have prepared right now?
What concentration spells do I have prepared as Torvin?
Tell me about Torvin's backstory and personality
What organisations is Kestrel affiliated with?
Which of my spells can I cast as rituals without using a slot?
What's my passive perception and investigation?

Look up your abilities mid-session

How does Uncanny Dodge work on Kestrel?
What does Hunter's Mark do — can I move it as a bonus action?
Show me the full text of the Alert feat on my character

Check the rules without leaving the table

What are the rules for grappling?
What does the Stunned condition do?
How does concentration work?
Remind me of the rules for death saving throws

Look up spells and equipment in the compendium

What does Silvery Barbs do?
Show me the stats for a Flame Tongue longsword
What's the difference between a Shortbow and a Longbow?

Read your sourcebooks

Show me the table of contents for the Player's Handbook
Read the Ranger class section from the 2024 Player's Handbook

Related MCP server: D&D Beyond MCP Server

For Dungeon Masters & Game Masters

Use Claude to plan sessions, build encounters, and run the table faster.

Get party stats

Show me the full party stats for campaign 6709239

Plan and rate encounters

How hard is this encounter for my party of 4 level 5 players:
2 trolls and a hill giant?
What CR should I target for a Moderate difficulty encounter
for my party of 3 level 8 characters?
Give me CR targets for a solo boss fight vs my party of 5 level 10s

Generate treasure

Roll a hoard for a CR 15 encounter for a level 12 party
Generate individual treasure for 4 bandits and their CR 5 captain

Look up monsters on the fly

Show me the full stat block for a Young Red Dragon
Find all Large undead with CR 5 or lower
What monsters have the Legendary Resistance trait?

Manage your campaign

List all the characters in my campaign
Show me the details for campaign 6709239 — who's playing what?

Read sourcebooks for prep

Read the Lair Actions section from the Monster Manual
What does the DMG say about setting DCs for ability checks?
Show me the treasure tables chapter from the Dungeon Master's Guide

Rule lookups mid-session

What are the rules for improvised weapons?
How does the Exhaustion condition work in 2024 rules?
Can a character use the Help action to assist with a skill check?

Full Tool Reference

Character Tools

Tool

Description

ddb_login

Authenticate with D&D Beyond (Wizards ID). Run once — session is saved to disk and reused.

ddb_logout

Revoke this server's local access: blocks further authenticated calls immediately, deletes the saved session file, and closes any open browser context. No account input, no remote logout call. See Logging out — this is a local-only logout, not a D&D Beyond account logout.

ddb_list_characters

List all characters in your account with ID, level, race, and class.

ddb_get_character

Parse a character into a compact, readable sheet. Covers all stats, skills, spells, actions, and inventory; LIMITED USE also lists items with rechargeable charges (wands, staffs, rods). Use sections to get just summary, combat, spells, inventory, features, concentration, notes, or full. Accepts name (fuzzy matched) or numeric ID. A Rules: line under the character's name gives the ruleset of the classes and lists content from other rulesets, which is also tagged inline ([2014], [homebrew], …).

ddb_get_character_raw

Fetch raw character JSON from the D&D Beyond API. Use ddb_get_character for all normal use.

ddb_download_character

Save a character's full JSON to a local file (must be under ~/Downloads or ~/Documents).

ddb_character_lookup

Look up the full description of a spell, feat, class feature, racial trait, or item on a character sheet. Supports partial and fuzzy name matching. Each result carries a Rules: line (a custom item reads custom item); a list of matches tags each line, except custom items, which stay untagged.

Campaign Tools

Tool

Description

ddb_list_campaigns

List all campaigns you're part of (as DM or player).

ddb_get_campaign

Fetch campaign details — DM, description, and active characters with their levels.

ddb_get_party

Fetch a compact summary of every character in a campaign — HP, AC, initiative, passive scores, ability scores, and skills for the whole party in one call. Each member carries a Rules: line, and classes, subclass, species and background from another ruleset are tagged.

Monster & Encounter Tools

Tool

Description

ddb_search_monsters

Search the D&D Beyond monster compendium by name, CR, type, size, or source (a book's short code such as mm-2024 or cos, its short name, or its title). Each result names its book and carries an edition tag ([2024], [2014], [homebrew], …). Where a monster exists in both editions, only the 2024 version is listed (rules_edition: "2014" lists the 2014 one), and the last line counts the hidden versions. When the requested version isn't available to your account but the other edition's is, that one is listed with a note saying so; entries that aren't available at all are counted under the header. A name matches at the start of a word ("goblin" finds Goblin Boss, not Hobgoblin), and when no name matches, D&D Beyond's closest hits (at most 10) are listed under a label saying so. At most 50 matches are listed, with the exact total and a hint on narrowing; list_all: true lists every match (a full list can be hundreds of KB, so use it after a search has reported the total). The first search with CR, type or size (or no name) reads the whole monster list, which takes several seconds; later ones are quick. A source lists that book's entries of either edition (at most 50 unless list_all), and wins over rules_edition; a book of the other edition adds a note. source: "homebrew" lists homebrew entries only (requires login). Works without logging in: free D&D Beyond content is listed as usual, and the rest is marked as not available without logging in. A cr other than 0, 0.125, 0.25, 0.5 or 1–30 is an error. Falls back to the Open5e SRD when D&D Beyond can't be reached.

ddb_get_monster

Get the full formatted stat block for a monster by name, with a Rules: line naming its edition and book. When a monster exists in both editions, the 2024 version is shown (rules_edition: "2014" shows the 2014 one); when the requested version isn't available to your account but the other edition's is, that one is shown and the output says so. Pass source (e.g. basic-rules-2014) for a specific book; it wins over rules_edition, and when the version shown isn't the rules_edition one a note says so. If that book's version isn't available to your account, the output names a book where an available version is. A book without that exact monster returns an error naming the books that do have it — never a different edition. source: "homebrew" looks up a homebrew entry only (requires login). Works without logging in: free D&D Beyond content is shown as usual; for locked content you get the SRD text when the SRD has it in the requested edition, else the free other-edition version or the stat block's header with a note to log in. Falls back to the Open5e SRD when D&D Beyond can't be reached.

ddb_rate_encounter

Rate encounter difficulty for a party. Defaults to 2024 XDMG rules (Low/Moderate/High). Set rules_edition: "2014" for classic DMG (Easy/Medium/Hard/Deadly), which also uses the 2014 stat block's CR. A Rules: line names the ruleset. Monsters are looked up automatically by exact or partial name (official entries only); a name that matches nothing is reported as not found rather than guessed, a partial name that fits several different creatures (e.g. "Red Dragon") lists each candidate with its CR instead of picking one, a monster whose CR isn't known asks you to supply cr, and a monster that couldn't be looked up because D&D Beyond was unreachable says so (Couldn't look up — D&D Beyond unreachable) rather than calling it not found.

ddb_encounter_cr

Given a party and target difficulty, returns recommended CRs broken down by encounter shape: solo boss, duo, squad, horde. Takes rules_edition (default "2024"; "2014" uses the classic DMG thresholds) and prints a Rules: line.

ddb_roll_treasure

Generate treasure using 2024 XDMG tables. hoard rolls once at the highest CR and includes magic items; individual rolls per monster. Monster names resolve the same way as in ddb_rate_encounter, including the ambiguous-name, unknown-CR and couldn't-look-up messages. Takes rules_edition; only 2024 tables exist, so the Rules: line names the 2024 DMG and "2014" says so. Limits: at most 20 monster entries, at most 100 per entry (applies to hoard too), at most 200 characters per monster name, and — for individual only — at most 100 total rolls across all entries. Over-budget requests are rejected with an error, never silently truncated.

Spell & Reference Tools

Tool

Description

ddb_search_spells

Search the full D&D Beyond spell compendium by name, level, school, concentration, or ritual. Defaults to 2024 spells; set rules_edition: "2014" for the 2014 versions. Each result is tagged [2024] / [2014], and the output says when the other edition is shown instead. Pass source (a book's slug, short name or title) to list that book's spells of either edition.

ddb_get_spell

Get the full description of any spell by name. Defaults to 2024; set rules_edition: "2014" for the 2014 text. A Rules: line names the ruleset, with a reason when the other edition is shown. Pass source to choose a specific book's version.

ddb_search_equipment

Search the item/equipment compendium by name, rarity, or type. Covers mundane weapons, armour, and magic items. Defaults to 2024; set rules_edition: "2014" for the 2014 versions. Each result is tagged [2024] / [2014]. Pass source (a book's slug, short name or title) to list that book's items of either edition; source: "homebrew" lists homebrew items only (requires login). rarity matches exactly (rare does not include Very Rare; mundane gear counts as Common).

ddb_get_equipment

Get the full stats and description of any item — weapon damage, properties, range, STR requirement, etc. Defaults to 2024; set rules_edition: "2014" for the 2014 version. A Rules: line names the ruleset, with a reason when the other edition is shown. Pass source to choose a specific book's version.

ddb_get_condition

Look up the rules text for a condition (Poisoned, Stunned, Grappled, etc.) in 2024 (default) or 2014 rules via rules_edition. No login required.

ddb_search_rules

Search the SRD rules chapters and their sections by keyword: SRD 5.2 (2024, 11 chapters) by default, SRD 5.1 (2014, 41 chapters) with rules_edition: "2014" or when 2024 has no match. No login required.

ddb_get_rules

Read the full text of an SRD rules chapter or section (Combat, Cover, Grappling, Multiclassing, Environment, etc.), SRD 5.2 by default and SRD 5.1 with rules_edition: "2014"; a miss in one SRD falls back to the other with a note. Supports query to jump to a keyword within long sections. No login required.

ddb_search_races

Search all races and subraces in the D&D Beyond compendium (including homebrew). Defaults to 2024; set rules_edition: "2014" for the 2014 versions. Each result is tagged [2024] / [2014]. Pass source (a book's slug, short name or title) to list that book's species of either edition. By default a 2024 species hides the 2014 subraces of the same base race (the 2024 Elf replaces High Elf and Wood Elf); name the subrace or use rules_edition: "2014" to see them.

ddb_search_classes

Search all classes with hit die and spellcasting info. Defaults to 2024; set rules_edition: "2014" for the 2014 versions. Each result is tagged [2024] / [2014]. Pass source (a book's slug, short name or title) to list that book's classes of either edition.

ddb_search_backgrounds

Search all backgrounds (including homebrew). Defaults to 2024; set rules_edition: "2014" for the 2014 versions. Each result is tagged [2024] / [2014]. Pass source (a book's slug, short name or title) to list that book's backgrounds of either edition.

ddb_search_feats

Search feats by name or prerequisite. Defaults to 2024; set rules_edition: "2014" for the 2014 versions. Each result is tagged [2024] / [2014]. Pass source (a book's slug, short name or title) to list that book's feats of either edition.

ddb_search_class_features

Search class, subclass, and optional class features by name, class or subclass, or level gained. Defaults to 2024; set rules_edition: "2014" for the 2014 versions. Each result is tagged [2024] / [2014]. Pass source (a book's slug, short name or title) to list that book's features of either edition. The edition is chosen per class or subclass: by default a class with a 2024 version lists only its 2024 features, and a feature only the 2014 class has is still found by name, tagged [2014].

ddb_search_racial_traits

Search racial traits, including optional ones, by name or species. Defaults to 2024; set rules_edition: "2014" for the 2014 versions. Each result is tagged [2024] / [2014]. Pass source (a book's slug, short name or title) to list that book's traits of either edition. By default a 2024 species hides the 2014 subraces of the same base race; name the subrace or use rules_edition: "2014" to see their traits.

In these searches, entries that aren't 2014 or 2024 content are tagged [homebrew], [third-party], [playtest] or [edition not stated] and are never hidden. When an entry exists in both editions, only the requested edition's version is listed and the last line counts the hidden ones. When one edition has the same entry in several books, the line names the book used and the others (also in … — pass source to choose). source: "homebrew" is reserved on these searches (as on the monster tools): it lists homebrew entries only, needs a login, and never falls back to the SRD.

Library & Navigation Tools

Tool

Description

ddb_list_library

List all sourcebooks you own, purchased, or have shared with you. Each book carries an edition tag ([2024], [2014], …).

ddb_read_book

Read content from an owned sourcebook by book slug (or plain title) and optional chapter. A Rules: line under the title names the book's ruleset.

ddb_search_site

Search D&D Beyond by keyword across spells, monsters, items, races, classes, and feats. Defaults to 2024; set rules_edition: "2014" for the 2014 versions. Each result is tagged [2024] / [2014]. Across all categories the reply has one Rules: header and one last line counting the hidden other-edition versions. Takes no source; use the per-category search tools to pick a book.

ddb_navigate

Navigate to any D&D Beyond URL and return its text content. Keeps the browser open for follow-up calls.

ddb_interact

Click, fill (requires confirm_fill: true), or screenshot the currently loaded page.

ddb_get_page

Return the text content of the currently loaded page.

ddb_close_browser

Close the background browser window. Call this when done with ddb_navigate, ddb_interact, or ddb_get_page.

ddb_clear_cache

Clear the server's in-memory caches so the next call re-fetches from D&D Beyond: spells (default; the reference compendium: spells, items, species, classes, backgrounds, feats, class features and racial traits), characters (character data and subclass always-prepared spell lists), monsters (stat blocks, the full monster list, the cached source list and the Open5e creature data), or all (everything, including the library list, campaigns and Open5e SRD data). Useful when results look like the SRD fallback right after logging in.


Prerequisites


Installation

🆕 New to all this? If you're on a Mac starting from scratch (no Homebrew, no Node, no Claude Desktop), follow the step-by-step beginner tutorial instead — it covers everything below plus how to install the prerequisites.

Add this to your MCP client's config — no separate install step needed. (ChatGPT uses a TOML file instead; see ChatGPT.)

{
  "mcpServers": {
    "dndbeyond": {
      "command": "npx",
      "args": ["-y", "@iamjameslennon/ddb-mcp"]
    }
  }
}

⚠️ Merge, don't append. These config files usually already exist and already have content (Claude Desktop writes its own "preferences" there on first launch). A JSON file holds exactly one top-level { … } object, so pasting this block at the end of the file produces a parse error. If the file already has an "mcpServers" key, add only the "dndbeyond": { … } entry inside it, comma-separated from its neighbours; if it doesn't, add "mcpServers" as a new key inside the existing outer braces. Verify before restarting your client:

python3 -m json.tool /path/to/your/config.json > /dev/null && echo "JSON OK"

On first launch, npx fetches the package itself (small — under 200 kB unpacked of JS). For the browser dependency: on first ddb_login, the server tries to launch your already-installed Google Chrome first — most macOS and Windows users get zero download. If Chrome isn't present, it falls back to downloading Playwright's bundled Chromium (~140 MB), with progress printed to the server log; subsequent logins reuse the cached browser. Set DDB_USE_BUNDLED_CHROMIUM=1 to skip the system-Chrome attempt and force the bundled path.

Configure the path to your client's config file in the Connecting to your MCP client section below.

To pin a version (recommended for production setups), change the args to ["-y", "@iamjameslennon/ddb-mcp@2.10.2"].

Alternative: install globally

If you'd rather have a persistent binary on PATH (offline use, air-gapped networks, faster startup):

npm install -g @iamjameslennon/ddb-mcp

Then use "command": "ddb-mcp" (no args) in your client config. The browser is still launched on first ddb_login (system Chrome if available, bundled Chromium otherwise) rather than during install.


Security & Privacy

  • Credentials stored: D&D Beyond session cookies are saved to a per-user config directory — ~/.config/ddb-mcp/session.json on macOS/Linux, %APPDATA%\ddb-mcp\session.json on Windows. Only cookies and site storage for dndbeyond.com and its subdomains are kept. A Wizards ID login through Google or Apple does not leave that provider's session in the file; those cookies are discarded when the session is saved, and a file that already contains them is rewritten the next time the server reads it.

  • File permissions: on macOS/Linux the file is 0600 and the directory 0700 — sessions created by older releases are tightened to these modes automatically on first use. On Windows access is restricted to your user account by default via %APPDATA% ACL inheritance — note that on multi-admin/domain-joined machines local administrators may also have read access.

  • Cobalt JWT: cached in memory only, never written to disk, and cleared on every session transition — a new login, an account swap (a different session file appearing), or ddb_logout.

  • Revocable session lifecycle: the server treats the on-disk session file as the single source of truth for "who am I logged in as." Every character/campaign/monster/reference cache described above is bound to that file's identity and is dropped the moment it changes — including deletion. ddb_logout makes this explicit and immediate for the local process; see Logging out for exactly what it does and does not guarantee.

  • Network access (outbound HTTPS only):

    • *.dndbeyond.com — character data, auth, campaigns, books

    • auth-service.dndbeyond.com — cobalt token exchange

    • api.open5e.com — SRD fallback, v2 (SRD 5.2 and 5.1; no auth)

  • Filesystem writes:

    • Session: ~/.config/ddb-mcp/session.json (macOS/Linux) or %APPDATA%\ddb-mcp\session.json (Windows)

    • Character downloads (opt-in): ~/Downloads or ~/Documents only — paths outside these roots are rejected

    • Screenshots (opt-in): ~/Downloads only

  • Transport: stdio only — the server opens no HTTP listeners and no ports.

  • ddb_roll_treasure work budget: bounded at both the MCP schema and the runtime level (direct callers of the underlying function bypass the schema, so the runtime check is not optional). Accepted requests: at most 20 monster entries, at most 100 per entry (per-entry limit applies to hoard requests too, not just individual), at most 200 characters per monster name, and — individual only — at most 100 total rolls summed across all entries (hoard always makes exactly one roll). Over-budget requests are rejected outright with an error naming the limit and how to reduce the request; counts are never silently clamped. The formatted output is separately capped at 32,000 characters — an oversized upstream monster name can't inflate the response, and aggregate coin totals are always shown in full even if per-roll detail is omitted for space.

  • Browser navigation allowlist: the browser tools are pinned to dndbeyond.com. ddb_navigate validates the URL up front, a network-layer guard blocks in-page escapes (link clicks, JS redirects, popups) to any other origin, and ddb_get_page refuses to return content from any page outside the allowlist.

  • Untrusted content: free text authored by D&D Beyond users is wrapped in <untrusted_dndbeyond_content> tags — scraped page text (ddb_navigate, ddb_get_page), book content (ddb_read_book), character notes/backstories (ddb_get_character, ddb_get_party), and homebrew entries. Homebrew monsters (ddb_get_monster, ddb_search_monsters), spells (ddb_get_spell, ddb_search_spells), items (ddb_get_equipment, ddb_search_equipment), feats, races, classes, backgrounds, class features and racial traits, plus homebrew or custom character features, spells and item descriptions (ddb_get_character, ddb_character_lookup, ddb_get_party), are wrapped. On the character sheet, each homebrew spell, item, weapon and action line is wrapped too, including actions granted by a homebrew class feature, racial trait, feat or item; a homebrew entry in a comma list (Cantrips, Spells, Inventory) moves to its own wrapped … (homebrew): line below the list. The same entries show up in ddb_search_site. Monster content is treated as homebrew unless D&D Beyond explicitly marks it official; other compendium entries are wrapped when D&D Beyond marks them homebrew. A custom background's feature text is always wrapped, and so is every line naming a player-made custom item. The character sheet's header wraps the character's name, and wraps its species / class line or Background line when a homebrew or custom entry is on it; a custom background in use shows its own name there, wrapped. Homebrew class names in SPELLCASTING are wrapped too, and languages typed as a custom proficiency, or proficiencies, languages, resistances, immunities and vulnerabilities that aren't known D&D Beyond values, move to their own wrapped … (custom): line. ddb_get_campaign, ddb_list_campaigns and ddb_list_characters wrap their whole reply, since campaign, character and player names are other people's text, as do ddb_get_character_raw (the whole character JSON) and ddb_download_character (its reply names the character; the saved file is plain JSON); ddb_get_party wraps the campaign name and any character it couldn't load. Official WotC text is left plain. Embedded delimiter tags in the content — including near-miss variants with extra whitespace, attributes, a missing > or HTML-entity encoding — are neutralized so it can't break out of the block. Homebrew from shared collections, party-member backstories and campaign notes are written by other people and may contain prompt-injection attempts — treat everything inside the tags as data, never as instructions. The confirm_click / confirm_fill gates on ddb_interact exist for exactly this reason.

  • Tool annotations & client permissions: every tool declares MCP behavior hints (readOnlyHint, destructiveHint, openWorldHint) so your MCP client can scope its permission prompts. The read-only tools (searches, lookups, character/campaign reads) are safe to auto-approve. Never auto-approve ddb_interact: its confirm_click/confirm_fill gates are set by the calling model, not by you, so your client's per-call permission prompt is the only human-in-the-loop check standing between a prompt-injected page and a click or form submission on your logged-in D&D Beyond session. ddb_login (writes credentials) and ddb_download_character (writes/overwrites local files) also warrant per-call approval. ddb_logout is also destructiveHint: true (it deletes the saved session file), though unlike the others it never talks to D&D Beyond and only ever narrows access.

  • Recommendation: pin the version in your MCP client config — "@iamjameslennon/ddb-mcp@2.10.2" — rather than letting npx auto-update on every launch.


Connecting to your MCP client

This server was built and tested with Claude, and also works in the ChatGPT desktop app. It speaks standard MCP over stdio, so other local MCP clients should work too, but only Claude and ChatGPT are documented here.

Merge the JSON config from the Installation section into this file (see the merge warning there if the file isn't empty), then quit and reopen Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json (community builds only — Claude Desktop has no official Linux release; use Claude Code instead)

Claude Code

One-liner — no manual JSON editing:

claude mcp add dndbeyond -- npx -y @iamjameslennon/ddb-mcp

Or if you installed globally:

claude mcp add dndbeyond ddb-mcp

ChatGPT (desktop app)

The ChatGPT desktop app runs local MCP servers through the same configuration as Codex, ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows). This file is TOML, not JSON. Add:

[mcp_servers.dndbeyond]
command = "npx"
args = ["-y", "@iamjameslennon/ddb-mcp"]
startup_timeout_sec = 60
tool_timeout_sec = 240

Or, with the Codex CLI installed, add the entry from the command line, then add the two timeout lines to it by hand:

codex mcp add dndbeyond -- npx -y @iamjameslennon/ddb-mcp

Then quit and reopen the ChatGPT app.

⚠️ Keep the timeouts. Without them, ChatGPT gives a server 10 s to start and each tool call 60 s. The first npx launch can take longer than 10 s, and ddb_login waits up to 3 minutes for you to finish signing in, so the defaults cut both off.

ChatGPT on the web can't reach a server running on your computer; use the desktop app.


First-time login

Run ddb_login once to authenticate:

ddb_login

A browser window will open and navigate to the D&D Beyond login page. Complete the login using your Wizards ID account (or Google or Apple); you have up to 3 minutes. Once D&D Beyond confirms you're signed in, the window closes and your session is automatically saved to a per-user config directory (~/.config/ddb-mcp/session.json on macOS/Linux, %APPDATA%\ddb-mcp\session.json on Windows) and reused on all future calls — no browser needed again until the session expires.


Finding character and campaign IDs

  • Character ID: the number in the character URL — dndbeyond.com/characters/140476673

  • Campaign ID: the number in the campaign URL — dndbeyond.com/campaigns/6709239

You can also use ddb_list_characters and ddb_list_campaigns to get IDs without leaving Claude.


Book slugs for ddb_read_book

Use ddb_list_library to get the slug for any book you own. Common examples:

Book

Slug

Player's Handbook (2024)

dnd/phb-2024

Dungeon Master's Guide (2024)

dnd/dmg-2024

Monster Manual (2024)

dnd/mm-2024

Player's Handbook (2014)

dnd/phb-2014

To read a specific chapter, pass the chapter path after the book slug:

Read the Ranger class section from the 2024 Player's Handbook
→ book_slug: "dnd/phb-2024", chapter_slug: "character-classes/ranger"

Sample ddb_get_character output

═══════════════════════════════════════
  Claude Skamos
  Rules: 2024 · 2014 content: 1 item · third-party: Dark Bargain (feat)
  Tiefling (Infernal) | Wizard 2 | Level 2
  Background: Sage | XP: 0
  Inspiration: No
═══════════════════════════════════════

HP: 10/10   Temp HP: —   Prof Bonus: +2
Hit Dice: 2d6 (2 remaining)
AC: 10   Initiative: +0   Speed: 30 ft.
Death Saves: Successes 0/3   Failures 0/3

ABILITY SCORES
  STR 8 (-1)  DEX 10 (+0)  CON 10 (+0)  INT 17 (+3)  WIS 15 (+2)  CHA 14 (+2)

SAVING THROWS
  STR -1   DEX +0   CON +0   INT +5*   WIS +4*   CHA +2
  (* proficient)

SKILLS
  Acrobatics (DEX)       +0
  Animal Handling (WIS)  +2
  Arcana (INT)           +5 *
  Athletics (STR)        -1
  Deception (CHA)        +2
  History (INT)          +7 **
  Insight (WIS)          +2
  Investigation (INT)    +5 *
  Perception (WIS)       +4 *
  ... (all 18 skills shown)
  (* proficient, ** expertise)

SENSES
  Passive Perception: 14   Passive Investigation: 15   Passive Insight: 12
  Darkvision 60 ft.

PROFICIENCIES & TRAINING
  Armor: None
  Weapons: Simple Weapons
  Tools: Calligrapher's Supplies
  Languages: Common, Common Sign Language, Draconic

DEFENSES
  Resistances: Fire
  Immunities: (none)
  Vulnerabilities: (none)
CONDITIONS: (none)

FEATS (1)
• Magic Initiate (Wizard): Two Cantrips. You learn two cantrips of your choice...

OTHER FEATURES
• Dark Bargain [third-party]
• Circle Magic (Intelligence)

CLASS FEATURES
• Core Wizard Traits (Wizard 1)
• Spellcasting (Wizard 1)
• Ritual Adept (Wizard 1)
• Arcane Recovery (Wizard 1)
• Scholar (Wizard 2)

RACIAL TRAITS
• Darkvision
• Otherworldly Presence
• Fiendish Legacy
• ...

ACTIONS
• Dagger           +2 to hit   1d4 piercing   reach 5 ft. / thrown 20/60 ft.   Finesse, Light, Thrown
• Quarterstaff     +1 to hit   1d6-1 bludgeoning (1d8-1 two-handed)   reach 5 ft.   Versatile
• Unarmed Strike   +1 to hit   0 bludgeoning   reach 5 ft.
• Chromatic Orb (1st level)  +5 to hit   3d8 acid/cold/fire/lightning/poison/thunder   range 90 ft.
• Fire Bolt (cantrip)        +5 to hit   1d10 fire   range 120 ft.

BONUS ACTIONS
  (none)

REACTIONS
• Opportunity Attack
• Shield (spell, 1st-level slot)

OTHER
• Arcane Recovery

LIMITED USE
• Arcane Recovery   0 used / 1 max   (Long Rest)

SPELLCASTING
  Wizard: INT  Spell Attack: +5  Save DC: 13

SPELL SLOTS
  Level 1: 3/3

SPELLS
  Cantrips: Mage Hand, Light, Message
  Spells: Comprehend Languages (L1 [ritual]), Detect Magic (L1 [ritual]),
          Find Familiar (L1 [ritual]), Magic Missile (L1), Shield (L1),
          Mage Armor (L1), Chromatic Orb (L1), Grease (L1), ...
  From Racial Trait: Fire Bolt, Thaumaturgy
  From Feat: Dancing Lights, Mending, Tasha's Hideous Laughter (L1)

INVENTORY
  Potion of Healing ×2; Spellbook [2014]; Parchment ×18; Backpack; Calligrapher's Supplies; Robe; ...

ATTUNEMENT (0/3): none

CURRENCY: 34gp, 7sp

Key things ddb_get_character handles correctly:

  • Wizards: only shows prepared spells and unprepared rituals (castable from spellbook without a slot) — not the full spellbook

  • Spell sources: racial traits, class features, feats, and magic items are all labelled separately

  • Ritual spells: marked with [ritual] in the spell list

  • Actions: weapons include to-hit bonus, damage (with the versatile die), reach or range, and properties, plus the mastery only for weapons the character has mastered; magic item bonuses (+1/+2/+3) are applied to both hit and damage

  • Bonus actions / reactions: spell-based bonus actions and reactions (Healing Word, Shield, Hunter's Mark, Hellish Rebuke, etc.) appear in the correct section with slot cost

  • AC: correctly calculates Unarmored Defense for Barbarians and Monks; Draconic Resilience base bump; Defense fighting style gated on equipped body armor; selects best armor when multiple items are equipped

  • Skills: Jack of All Trades applied for Bards; Remarkable Athlete for Champion Fighters (STR/DEX/CON only); expertise marked with **

  • Initiative: Alert feat and Jack of All Trades bonuses applied correctly, with 2014/2024 rule differences handled

  • Global save and ability-check bonuses: Stone of Good Luck (Luckstone), Ring of Protection, Cloak of Protection, and Paladin Aura of Protection apply across every save and skill / passive score

  • Multiclass: hit dice shown per class, spell slots computed from combined caster levels, save proficiencies correctly come only from the starting class

  • 2014 race ASIs: Half-Elf and Variant Human chosen +1 ability bonuses are applied alongside the fixed grants; 2024 declined race ASIs (moved to background origin feat) are correctly ignored


Upgrading

npm update -g @iamjameslennon/ddb-mcp

Then restart your MCP client (in Claude Code, run /mcp to reconnect the server). With the npx config, quitting and reopening the client is enough to pick up a new release, unless you pinned a version.


Session storage

Your session is saved to a per-user config directory:

  • macOS/Linux: ~/.config/ddb-mcp/session.json

  • Windows: %APPDATA%\ddb-mcp\session.json

This file holds only D&D Beyond cookies and site storage (dndbeyond.com and its subdomains). A sign-in that goes through Google or Apple does not store that provider's session here. Keep the file private — it grants access to your D&D Beyond account.


Logging out

If your server has ddb_logout, use it — it's the preferred way to log out. Run it as a tool call:

ddb_logout

ddb_logout takes no input and never calls D&D Beyond. It blocks any further authenticated tool call immediately (tools that work logged out, such as monster lookups, carry on exactly as for someone who never logged in), deletes the local session file, and closes any browser context the server had open. Repeated calls are safe — logging out when you were never logged in, or logging out twice, both report success. If a call fails (e.g. the session file can't be deleted because of a filesystem permission problem, or the browser refuses to close), the tool's error message says exactly which step failed — local access is still revoked for the rest of that failure, it's only the file and/or browser cleanup that didn't finish. It never silently falls back to letting the old session keep working.

On an older version without ddb_logout, log out manually:

  1. Stop the MCP server (close your MCP client, or otherwise terminate the ddb-mcp process).

  2. Delete the session file:

    # macOS/Linux
    rm ~/.config/ddb-mcp/session.json
    
    # Windows (PowerShell)
    Remove-Item "$env:APPDATA\ddb-mcp\session.json"
  3. Restart the server.

Important caveats, on every version:

  • This is a local logout only — it is NOT a D&D Beyond account logout. It removes this server's local copy of your session; it does not sign you out of dndbeyond.com in a browser, does not invalidate the session on D&D Beyond's servers, and does not revoke any other device or app using the same account. To sign out of D&D Beyond itself, do that on the website directly.

  • Detection happens at the next protected operation, not instantly. If the session file is deleted or replaced by something other than ddb_logout (manually, by another process, or by an older-version workaround while the server keeps running), the running server only notices the next time it goes to use the old credentials — it re-reads the file at that point and refuses to proceed with the stale session. This means:

    • A request already in flight when the file changes is not retracted — it was dispatched under the old credentials before the change was observed.

    • Idle browser activity (an already-open background browser window/context) is not torn down immediately just because the file changed on disk; it's closed on the next transition the server observes, not the instant the file disappears.

    • If you need immediate termination — no in-flight requests, no lingering browser window — stop the MCP server process itself. That's the only action that's instantaneous; deleting the file (with the server still running) is not.


Configuration

Variable

Default

Description

DDB_CHARACTER_CACHE_TTL

60

Character sheet cache lifetime in seconds. Lower values give fresher HP/spell slot data during live play at the cost of more API calls. Set to 10 for active sessions, leave at default for prep work.

DDB_NO_SANDBOX

—

Set to 1 to disable Chromium sandboxing. Required in some container/CI environments.

DDB_USE_BUNDLED_CHROMIUM

—

Set to 1 to skip your installed Google Chrome and use Playwright's bundled Chromium for ddb_login and the browser tools.


Troubleshooting

"Not logged in" or 403 errors Your session has expired. Run ddb_login to re-authenticate.

Browser won't launch on ddb_login The server prefers your installed Google Chrome and falls back to Playwright's bundled Chromium if Chrome isn't present. If the bundled-Chromium fallback is in use and its download failed (network or sandbox issue), run ddb_login again — the server retries on each call. To fetch the bundled browser manually:

npx playwright install chromium

The same global Playwright cache is shared by every install path (npx, global, local clone) — one successful install is reused everywhere. If your system Chrome is broken or outdated and you want to force the bundled path, set DDB_USE_BUNDLED_CHROMIUM=1.

Character returns 403 or "private" The character is set to private on D&D Beyond. You must be logged in as the owner, or the owner must make it public.

MCP server not appearing in Claude Code Run /mcp in Claude Code to reconnect. If it still doesn't appear, run claude mcp list to confirm the dndbeyond entry exists.

Server crashes on startup Make sure you're running Node.js 22 or later: node --version.


Development

# Install dependencies — prefer npm ci to respect the lockfile
npm ci

# Run in development mode (no build step needed). Chromium is fetched lazily
# on first `ddb_login`; if you want to pre-warm the cache:
#   npx playwright install chromium
npm run dev

# Build
npm run build

# Lint and type-check
npm run lint
npm run typecheck

# Watch mode
npm run build:watch

# Run tests (browser-free — they mock the Playwright surface)
npm test

Testing your change in Claude Desktop

After npm test, check your change the way users meet it, through an AI client. The repo ships a skill, skills/ddb-mcp-regression/, that has the AI play players and DMs across every tool and all the test characters in testcharacters.md, judge whether each reply suits the user, and write a findings report you can hand to a coding assistant.

  1. Build your change: npm run build.

  2. Point Claude Desktop at your build. In the config file listed under Claude Desktop, set the server to your checkout instead of the npm package, then restart Claude Desktop:

    {
      "mcpServers": {
        "dndbeyond": {
          "command": "node",
          "args": ["/absolute/path/to/ddb-mcp/dist/index.js"]
        }
      }
    }

    Rebuild and restart Claude Desktop after each further change.

  3. Load the skill. Zip the skill folder so the zip contains ddb-mcp-regression/SKILL.md and ddb-mcp-regression/references/:

    cd skills && zip -r ddb-mcp-regression.zip ddb-mcp-regression

    Upload the zip in Claude Desktop's Skills settings (under Settings → Capabilities at the time of writing). Custom skills need "Code execution and file creation" turned on, which also lets the AI save the report as a file. If the upload is rejected, zip the folder's contents instead and open an issue so this step can be corrected. In a client without skills, paste SKILL.md into the chat and attach the files in references/.

  4. Run it: ask "Run the ddb-mcp regression skill on my change". It tells you up front what it will do on your machine (a sign-in window if you aren't logged in, one character JSON saved to ~/Downloads, and logging out at the end only if you agree), works in batches, and keeps notes so a long run can resume.

  5. Read the report. You get ddb-mcp-regression-<date>.md (or the same report printed in the chat). It lists findings with evidence and severity, known issues it saw, what it couldn't cover, and ready-to-paste prompts for a coding assistant. Nothing needs committing: keep it, or attach it to your PR.


Credits

Forked from ddb-mcp/ddb-mcp. The monster, reference, and session-workflow tooling was inspired by dndbeyond-mcp. This fork significantly expands character parsing, adds session-based API fetching, and introduces compendium, reference, encounter, and treasure tools.

Character parsing improvements:

  • Complete stat block: saving throws, all 18 skills with proficiency/expertise markers, senses (passive scores + darkvision/tremorsense), proficiencies & training (armor, weapons, tools, languages), damage resistances/immunities/vulnerabilities, conditions, inspiration, death saves, hit dice per class

  • Accurate AC: Unarmored Defense calculated correctly for Barbarians (10 + DEX + CON) and Monks (10 + DEX + WIS); when multiple armors are equipped, picks the best-AC combination; shield stacks additively

  • Correct spell display for Wizards: shows only prepared spells and unprepared rituals — not the full spellbook

  • All spell sources: racial traits, class features, feats, and magic items each labelled separately

  • Ritual spells: marked with [ritual]

  • Full action classification: bonus actions and reactions list both class features and spell-based entries with slot cost

  • Magic weapon bonuses: enhancement bonuses (+1/+2/+3) applied to both to-hit and damage

  • Weapon properties and mastery: all properties shown per weapon, and a mastery only for weapons the character has mastered

  • Skill and initiative accuracy: Jack of All Trades and Alert feat handled correctly for both 2014 and 2024 rules

  • Multiclass support: hit dice per class, spell slots from combined caster levels

Other improvements:

  • Session-based API fetching (no browser required after login for most tools)

  • Encounter difficulty rating for both 2024 XDMG and 2014 DMG rules

  • Treasure generation using 2024 XDMG tables

  • SRD rules search and retrieval (no login required)

  • Security: path constraints on file writes, slug validation, session file permissions (0600), prompt injection gate on browser form fills


License

MIT

This work includes material from the System Reference Document 5.2 by Wizards of the Coast LLC, licensed under CC-BY-4.0. The 2024 text served by ddb_get_condition, and the Open5e SRD 5.2 content used as a fallback, come from SRD 5.2.1 under CC-BY-4.0.

Available Tools

35 tools
ddb_character_lookupA
Read-only

Look up the full description of a spell, feat, class feature, subclass feature, racial trait, background feature, or equipped item by name. Supports partial and fuzzy name matching (e.g. 'cutting' finds Cutting Words, 'sheild' finds Shield). Accepts either a numeric character_id or a character_name. Requires login — run ddb_login first if you haven't already.

Inputs: name (required), character_id, character_name.

ddb_clear_cacheA
Idempotent

Wipe in-process caches so the next call re-fetches from D&D Beyond. Use this when search results look like the SRD/Open5e fallback (e.g. 2024 cantrips missing from spell results) after you've logged in — the partial compendium build is cached for up to 5 minutes and this forces an immediate retry. cache='spells' (default) clears just the spell/reference compendium; 'all' wipes every cache.

Inputs: cache.

ddb_close_browserA
Idempotent

Close the background browser window if one is open. Useful after running ddb_navigate, ddb_interact, or ddb_get_page.

Inputs: no named parameters.

ddb_download_characterA
DestructiveIdempotent

Download a character's full JSON data to a local file. Requires login — run ddb_login first if you haven't already.

Inputs: character_id (required), output_path.

ddb_encounter_crA
Read-only

Given a party and a target difficulty, returns the CR to aim for — broken down by encounter shape (solo boss, duo, squad, horde). Defaults to 2024 XDMG rules; set rules_edition to '2014' for classic DMG. No monster lookup required. Use with ddb_rate_encounter to verify a specific monster list.

Inputs: party (required), difficulty (required), monster_count, rules_edition.

ddb_get_campaignA
Read-only

Fetch campaign information including player characters from a D&D Beyond campaign. Requires login — run ddb_login first if you haven't already.

Inputs: campaign_id (required).

ddb_get_characterA
Read-only

Parse and display a character sheet. Use sections to reduce output: summary (vitals+stats), combat (adds actions/weapons), spells (spellcasting only), inventory, features, concentration, notes (backstory, traits, bonds), or full (default). Requires login — run ddb_login first if you haven't already.

Inputs: sections, character_id, character_name.

ddb_get_character_rawA
Read-only

Returns raw 300–500 KB character JSON. Requires confirm_large_response: true. Use ddb_get_character instead for all normal use. Requires login — run ddb_login first if you haven't already.

Inputs: confirm_large_response (required), character_id, character_name.

ddb_get_conditionA
Read-only

Look up the rules text for a D&D condition (Blinded, Charmed, Frightened, Grappled, etc.). No login required.

Inputs: name (required).

ddb_get_equipmentA
Read-only

Get the full stats and description of any item or equipment in the D&D Beyond compendium by name. Works for mundane weapons (e.g. 'Longbow'), armour (e.g. 'Plate'), adventuring gear, and magic items. Requires login.

Inputs: name (required).

ddb_get_monsterA
Read-only

Get the full stat block for a specific monster from the D&D Beyond compendium. Searches by name (partial match). Requires login.

Inputs: name (required).

ddb_get_pageA
Read-only

Return the text content of the currently loaded page in the browser. The browser stays open — call ddb_close_browser when finished.

Inputs: no named parameters.

ddb_get_partyA
Read-only

Fetch a compact summary of every character in a campaign. Returns HP, AC, initiative, passive scores, ability scores, and skills for the whole party in one call. Requires login — run ddb_login first if you haven't already.

Inputs: campaign_id (required).

ddb_get_rulesA
Read-only

Get the full SRD rules text for a topic by section name or slug. Covers all core 5e rules: Spellcasting, Abilities, Attacking, Combat Sequence, Actions in Combat, Damage and Healing, Conditions, Movement, Multiclassing, Rest, Saving Throws, Environment, Traps, Diseases, Madness, Poisons, Weapons, Armor, and more. Use query to jump to a specific topic within a long section. For non-SRD rules or more detail, use ddb_read_book. No login required.

Inputs: name (required), query, max_chars.

ddb_get_spellA
Read-only

Get the full description of any spell in the D&D Beyond compendium by name. Not limited to a character's known spells. Requires login.

Inputs: name (required).

ddb_interactA
Destructive

Interact with the currently loaded D&D Beyond page by clicking, filling a form field, or taking a screenshot. The 'click' and 'fill' actions require confirm_click / confirm_fill: true — safety gates to prevent prompt injection on rendered DDB pages from triggering unintended state changes (deleting a character, leaving a campaign, posting to a forum). Screenshots are unguarded — they are read-only.

Inputs: action (required), selector (required), value, confirm_fill, +1 more.

ddb_list_campaignsA
Read-only

List all D&D Beyond campaigns you are part of (as DM or player). Requires login — run ddb_login first if you haven't already.

Inputs: no named parameters.

ddb_list_charactersA
Read-only

List all characters in your D&D Beyond account, including their ID, level, race, and class. Requires login — run ddb_login first if you haven't already.

Inputs: no named parameters.

ddb_list_libraryA
Read-only

List all books and sourcebooks you own in your D&D Beyond library. Requires login — run ddb_login first if you haven't already.

Inputs: no named parameters.

ddb_loginA
Idempotent

Launch a browser and log into D&D Beyond. A Chrome window will open for you to complete login — it closes automatically once your session is saved. After that, character tools work without any browser.

Inputs: no named parameters.

ddb_navigateA
Read-only

Navigate to any D&D Beyond URL and return the page's text content. Only dndbeyond.com URLs are allowed. The browser stays open after this call for follow-up ddb_interact or ddb_get_page calls. Call ddb_close_browser when finished.

Inputs: url (required).

ddb_rate_encounterA
Read-only

Rate the difficulty of a D&D encounter. Defaults to 2024 XDMG rules (Low/Moderate/High, no multiplier). Set rules_edition to '2014' for the classic DMG XP threshold method (Easy/Medium/Hard/Deadly with encounter multiplier). Monsters are looked up in the compendium automatically — supply 'cr' directly for homebrew.

Inputs: party (required), monsters (required), rules_edition.

ddb_read_bookA
Read-only

Read a D&D Beyond book. Accepts either a slug (e.g. dnd/phb-2024) or a plain title (e.g. "Player's Handbook" or "monster manual") — the server resolves titles against your library automatically. Specify chapter_slug for a chapter, query to jump to a heading, and max_chars to control response size. Requires login — run ddb_login first if you haven't already.

Inputs: book_slug (required), query, max_chars, chapter_slug.

ddb_roll_treasureA
Read-only

Generate a treasure reward using the 2024 XDMG treasure tables (default). Provide either a CR directly or a list of monster names — CR is resolved automatically via fuzzy name matching. treasure_type 'hoard' makes one roll using the highest CR and includes magic items (requires character_level); 'individual' rolls once per monster and sums the results.

Inputs: cr, monsters, treasure_type, character_level.

ddb_search_backgroundsA
Read-only

Search all D&D Beyond backgrounds (including homebrew). Requires login — run ddb_login first if you haven't already.

Inputs: name, limit, offset.

ddb_search_classesA
Read-only

Search all D&D Beyond classes with hit die, spellcasting, and subclasses. Requires login — run ddb_login first if you haven't already.

Inputs: name, limit, offset.

ddb_search_class_featuresA
Read-only

Search class features by name, class, or level gained. Requires login — run ddb_login first if you haven't already.

Inputs: name, level, limit, offset, +1 more.

ddb_search_equipmentA
Read-only

Search the D&D Beyond item/equipment compendium by name, rarity, or type. Covers mundane weapons (Longsword, Shortbow), armour (Plate, Chain Mail), adventuring gear, and magic items. Filter by rarity='common' to see only mundane equipment. Requires login.

Inputs: name, type, rarity.

ddb_search_featsA
Read-only

Search feats by name or prerequisite text. Requires login — run ddb_login first if you haven't already.

Inputs: name, limit, offset, prerequisite.

ddb_search_monstersA
Read-only

Search the D&D Beyond monster compendium by name, CR, type, or size. Returns a summary list. Use ddb_get_monster for the full stat block. Requires login.

Inputs: cr, name, size, type.

ddb_search_racesA
Read-only

Search all D&D Beyond races and subraces (including homebrew). Not character-specific. Requires login — run ddb_login first if you haven't already.

Inputs: name, limit, offset.

ddb_search_racial_traitsA
Read-only

Search racial traits by name or race. Requires login — run ddb_login first if you haven't already.

Inputs: name, limit, offset, race_name.

ddb_search_rulesA
Read-only

Search the SRD rules sections by keyword. Searches across section names and full content — e.g. 'grapple' finds the Attacking section (which covers grapple rules) and the Conditions section (which has the Grappled condition). Returns a list of matching sections with their slugs. Use ddb_get_rules to read the full text of a section. No login required.

Inputs: query.

ddb_search_siteB
Read-only

Search D&D Beyond for spells, monsters, magic items, races, classes, or feats.

Inputs: query (required), category.

ddb_search_spellsA
Read-only

Search the full D&D Beyond spell compendium by name, level, school, concentration, or ritual. First call builds the compendium (slow); subsequent calls are instant. Requires login.

Inputs: name, level, limit, offset, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 35 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: search_* vs get_* vs list_*, plus unique tools like ddb_login and ddb_rate_encounter. Minor overlap exists between ddb_search_site and the specific compendium searches, and between ddb_get_rules and ddb_get_condition, but descriptions help clarify.

    Naming Consistency4/5

    The ddb_ prefix and common verbs (search_*, get_*, list_*) create a predictable pattern. Deviations like ddb_character_lookup (instead of ddb_lookup_character) and single-word verbs (ddb_login, ddb_navigate, ddb_interact) break the convention slightly, but the overall scheme remains readable.

    Tool Count2/5

    With 35 tools, this is well beyond the 25+ threshold and feels heavy for an agent to navigate. While the domain is broad, many tools could be consolidated (e.g., a single compendium search with type filters) or the server could be split into focused servers.

    Completeness3/5

    The tool surface is extensive, covering characters, campaigns, compendium searches, rules, books, browser automation, and encounter tools. However, there are notable gaps: you can search for feats, races, classes, backgrounds, and class features, but there are no corresponding ddb_get_* tools for these categories (only ddb_character_lookup which requires a character). This makes it impossible to directly retrieve full details for those compendium items.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A comprehensive Model Context Protocol server for managing Dungeons & Dragons campaigns with tools for characters, NPCs, locations, quests, combat encounters, and session tracking.
      30
      16
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides Claude direct access to D\&D Beyond accounts to manage characters, campaigns, and sourcebook content. It enables users to search for spells and monsters, retrieve character data, and read owned digital books through an authenticated session.
      8
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI assistants to Dungeons & Dragons 5e game information via the Model Context Protocol, enabling queries for spells, monsters, equipment, and more.
      54
      MIT