D&D Beyond MCP Server
Connects Claude/ChatGPT to D&D Beyond so it can read characters, campaigns, sourcebooks, compendium content, rules, and run encounter/treasure planning.
Authenticate to D&D Beyond, clear caches, and close browser sessions.
List/read characters, get parsed sheets by ID/name, fetch raw JSON, download JSON, and look up character features/spells/items.
List/get campaigns and party summaries.
Search/get monsters, spells, equipment, races, classes, backgrounds, feats, class features, and racial traits.
List owned sourcebooks and read book content by slug/title/chapter.
Search/read SRD rules and conditions without login.
Rate encounters and recommend CR targets by party, difficulty, and rules edition.
Generate individual/hoard treasure using 2024 XDMG tables.
Navigate D&D Beyond pages, interact via click/fill/screenshot, and get page text.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@D&D Beyond MCP Server What does Silvery Barbs do?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 TorvinWhat spells do I have prepared right now?What concentration spells do I have prepared as Torvin?Tell me about Torvin's backstory and personalityWhat 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 characterCheck 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 throwsLook up spells and equipment in the compendium
What does Silvery Barbs do?Show me the stats for a Flame Tongue longswordWhat's the difference between a Shortbow and a Longbow?Read your sourcebooks
Show me the table of contents for the Player's HandbookRead the Ranger class section from the 2024 Player's HandbookRelated 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 6709239Plan 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 10sGenerate treasure
Roll a hoard for a CR 15 encounter for a level 12 partyGenerate individual treasure for 4 bandits and their CR 5 captainLook up monsters on the fly
Show me the full stat block for a Young Red DragonFind all Large undead with CR 5 or lowerWhat monsters have the Legendary Resistance trait?Manage your campaign
List all the characters in my campaignShow me the details for campaign 6709239 — who's playing what?Read sourcebooks for prep
Read the Lair Actions section from the Monster ManualWhat does the DMG say about setting DCs for ability checks?Show me the treasure tables chapter from the Dungeon Master's GuideRule 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 |
| Authenticate with D&D Beyond (Wizards ID). Run once — session is saved to disk and reused. |
| 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. |
| List all characters in your account with ID, level, race, and class. |
| 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 |
| Fetch raw character JSON from the D&D Beyond API. Use |
| Save a character's full JSON to a local file (must be under ~/Downloads or ~/Documents). |
| 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 |
Campaign Tools
Tool | Description |
| List all campaigns you're part of (as DM or player). |
| Fetch campaign details — DM, description, and active characters with their levels. |
| 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 |
Monster & Encounter Tools
Tool | Description |
| Search the D&D Beyond monster compendium by name, CR, type, size, or |
| Get the full formatted stat block for a monster by name, with a |
| Rate encounter difficulty for a party. Defaults to 2024 XDMG rules (Low/Moderate/High). Set |
| Given a party and target difficulty, returns recommended CRs broken down by encounter shape: solo boss, duo, squad, horde. Takes |
| Generate treasure using 2024 XDMG tables. |
Spell & Reference Tools
Tool | Description |
| Search the full D&D Beyond spell compendium by name, level, school, concentration, or ritual. Defaults to 2024 spells; set |
| Get the full description of any spell by name. Defaults to 2024; set |
| Search the item/equipment compendium by name, rarity, or type. Covers mundane weapons, armour, and magic items. Defaults to 2024; set |
| Get the full stats and description of any item — weapon damage, properties, range, STR requirement, etc. Defaults to 2024; set |
| Look up the rules text for a condition (Poisoned, Stunned, Grappled, etc.) in 2024 (default) or 2014 rules via |
| 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 |
| 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 |
| Search all races and subraces in the D&D Beyond compendium (including homebrew). Defaults to 2024; set |
| Search all classes with hit die and spellcasting info. Defaults to 2024; set |
| Search all backgrounds (including homebrew). Defaults to 2024; set |
| Search feats by name or prerequisite. Defaults to 2024; set |
| Search class, subclass, and optional class features by name, class or subclass, or level gained. Defaults to 2024; set |
| Search racial traits, including optional ones, by name or species. Defaults to 2024; set |
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 |
| List all sourcebooks you own, purchased, or have shared with you. Each book carries an edition tag ( |
| Read content from an owned sourcebook by book slug (or plain title) and optional chapter. A |
| Search D&D Beyond by keyword across spells, monsters, items, races, classes, and feats. Defaults to 2024; set |
| Navigate to any D&D Beyond URL and return its text content. Keeps the browser open for follow-up calls. |
| Click, fill (requires |
| Return the text content of the currently loaded page. |
| Close the background browser window. Call this when done with |
| Clear the server's in-memory caches so the next call re-fetches from D&D Beyond: |
Prerequisites
Node.js 22 or later
An MCP client: Claude Desktop, Claude Code, or the ChatGPT desktop app
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-mcpThen 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.jsonon macOS/Linux,%APPDATA%\ddb-mcp\session.jsonon Windows. Only cookies and site storage fordndbeyond.comand 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
0600and the directory0700— 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_logoutmakes 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, booksauth-service.dndbeyond.com— cobalt token exchangeapi.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):
~/Downloadsor~/Documentsonly — paths outside these roots are rejectedScreenshots (opt-in):
~/Downloadsonly
Transport: stdio only — the server opens no HTTP listeners and no ports.
ddb_roll_treasurework 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 tohoardrequests too, not justindividual), at most 200 characters per monster name, and —individualonly — at most 100 total rolls summed across all entries (hoardalways 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_navigatevalidates the URL up front, a network-layer guard blocks in-page escapes (link clicks, JS redirects, popups) to any other origin, andddb_get_pagerefuses 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 inddb_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_campaignsandddb_list_characterswrap their whole reply, since campaign, character and player names are other people's text, as doddb_get_character_raw(the whole character JSON) andddb_download_character(its reply names the character; the saved file is plain JSON);ddb_get_partywraps 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. Theconfirm_click/confirm_fillgates onddb_interactexist 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-approveddb_interact: itsconfirm_click/confirm_fillgates 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) andddb_download_character(writes/overwrites local files) also warrant per-call approval.ddb_logoutis alsodestructiveHint: 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 lettingnpxauto-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.
Claude Desktop (recommended)
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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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-mcpOr if you installed globally:
claude mcp add dndbeyond ddb-mcpChatGPT (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 = 240Or, 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-mcpThen 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
npxlaunch can take longer than 10 s, andddb_loginwaits 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_loginA 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/140476673Campaign 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) |
|
Dungeon Master's Guide (2024) |
|
Monster Manual (2024) |
|
Player's Handbook (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, 7spKey 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 listActions: 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-mcpThen 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.jsonWindows:
%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_logoutddb_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:
Stop the MCP server (close your MCP client, or otherwise terminate the
ddb-mcpprocess).Delete the session file:
# macOS/Linux rm ~/.config/ddb-mcp/session.json # Windows (PowerShell) Remove-Item "$env:APPDATA\ddb-mcp\session.json"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 |
|
| 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 |
| — | Set to |
| — | Set to |
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 chromiumThe 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 testTesting 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.
Build your change:
npm run build.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.
Load the skill. Zip the skill folder so the zip contains
ddb-mcp-regression/SKILL.mdandddb-mcp-regression/references/:cd skills && zip -r ddb-mcp-regression.zip ddb-mcp-regressionUpload 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.mdinto the chat and attach the files inreferences/.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.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 toolsddb_character_lookupARead-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_cacheAIdempotent
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_browserAIdempotent
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_characterADestructiveIdempotent
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_crARead-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_campaignARead-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_characterARead-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_rawARead-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_conditionARead-only
Look up the rules text for a D&D condition (Blinded, Charmed, Frightened, Grappled, etc.). No login required.
Inputs: name (required).
ddb_get_equipmentARead-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_monsterARead-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_pageARead-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_partyARead-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_rulesARead-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_spellARead-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_interactADestructive
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_campaignsARead-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_charactersARead-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_libraryARead-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_loginAIdempotent
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_rate_encounterARead-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_bookARead-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_treasureARead-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_backgroundsARead-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_classesARead-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_featuresARead-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_equipmentARead-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_featsARead-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_monstersARead-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_racesARead-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_traitsARead-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_rulesARead-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_siteBRead-only
Search D&D Beyond for spells, monsters, magic items, races, classes, or feats.
Inputs: query (required), category.
ddb_search_spellsARead-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
Scored across 35 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
Official remote MCP server for Archivist AI TTRPG campaign memory: characters, sessions, and more.
Remote MCP server for D&D: read and update your CharGen campaigns, generate NPCs and art.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseBqualityDmaintenanceA comprehensive Model Context Protocol server for managing Dungeons & Dragons campaigns with tools for characters, NPCs, locations, quests, combat encounters, and session tracking.3016MIT
- FlicenseNot gradedqualityDmaintenanceAn 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-
- AlicenseNot gradedqualityDmaintenanceConnects AI assistants to Dungeons & Dragons 5e game information via the Model Context Protocol, enabling queries for spells, monsters, equipment, and more.54MIT
- FlicenseNot gradedqualityDmaintenanceA local MCP server that provides access to D&D Beyond character sheets, SRD content (spells, monsters, items), a dice roller, and optional campaign tools via undocumented endpoints.-