beyond-mcp

D&D Beyond MCP server: character sheets, monster statblocks, campaign rosters, a live game-log roll feed, and opt-in sheet writes. Extracted from roll20-dm-mcp per its issue #171 so DDB rides behind its own MCP seam — the dm-whisper gem and Claude Code select it by config, next to interchangeable VTT-primitive servers (roll20-dm-mcp today, forge-mcp/ddb-maps-mcp later).

This server knows nothing about Roll20 or any VTT, and it never opens a browser. Reads are always on; writes are opt-in (DDB_WRITES=enabled).

Formerly ddb-mcp; renamed to avoid a collision with the unrelated public ddb-mcp/ddb-mcp. Old repo URLs redirect.

Tools

Tool names and default output shapes match what roll20-dm-mcp served, so existing callers migrate by pointing at this server. The roll pump differs by design: it buffers instead of posting to Roll20 — the gem drains it and bridges rolls via roll20-dm-mcp's post_roll_as_character.

Write tools (opt-in — DDB_WRITES=enabled)

Reads are always available; these mutation tools register only when the deployment sets DDB_WRITES=enabled, so prep-time and default installs stay read-only. They are primitives — they effect exactly the change asked on whatever character id they're given, with no policy about who owns the sheet. Because DDB PC HP is also driven by Beyond20 and the player's own edits, writes race those (last-writer-wins) and are meant as the DM's deliberate acts.

Related MCP server: DM20 Protocol

Auth

Reads authenticate with the D&D Beyond CobaltSession cookie (exchanged for a short-lived JWT; see docs/ddb-browserless-protocol.md). The cookie is consumed, never harvested: supply DDB_COBALT in the env, or point DDB_DATA_DIR at the directory where the gem writes ddb-cobalt.json. Absent or expired cookie ⇒ every read fails loudly with re-harvest instructions.

Config

Running

npm install
npm run build
npm start            # stdio MCP server (Claude Code .mcp.json, gem supervised spawn)
npm run serve        # HTTP MCP server on /mcp + rolls SSE on /events (bearer-authed)

Claude Code .mcp.json:

{
  "mcpServers": {
    "ddb": { "command": "node", "args": ["E:/personalProjects/beyond-mcp/dist/index.js"] }
  }
}

Development

npm test             # vitest run
npx vitest run src/bridge/ddb-gamelog.test.ts   # one file
npm run lint
npm run dev          # tsx watch, stdio

Node 20+, TypeScript (NodeNext ESM), vitest — same conventions as roll20-dm-mcp.