# D&D Beyond MCP

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

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

## Tools

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

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

## Setup

1. Install Python 3.10+ and the dependencies:

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

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

   ```bash
   python3 server.py
   ```

## Testing

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

```bash
python tests/test_smoke.py
```

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

```bash
python tests/test_smoke.py --character 24998307
```

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

## Connect to Claude Desktop

Edit your Claude Desktop config file:

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

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

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

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

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

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

## Enabling the campaign tools (optional)

`list_campaigns` and `get_campaign` need your login session:

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

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

## Notes & limitations

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