D&D 5E MCP Server

An MCP server that gives AI assistants access to D&D 5th Edition content from the Open5e API: spells, monsters, classes, species, equipment, rules references, plus encounter-building and character-build helpers. It uses Open5e’s v2 API.

Requirements

• Node.js 20 or newer (developed against Node 26)
• Network access to api.open5e.com

Setup

npm install
npm run build

Connecting a client

The server speaks JSON-RPC over stdio. Point your MCP client at the built entry point:

{
  "mcpServers": {
    "dnd-5e": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/dnd-mcp"
    }
  }
}

Set cwd to wherever you cloned this repository. A starting point is in mcp.json.

Verify it responds:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node dist/index.js

Tools

Every tool except get_api_stats also takes two optional arguments that restrict it to some sourcebooks:

• ruleset: "5e-2014", "5e-2024" or "a5e";
• sources: Open5e document keys, e.g. ["srd-2014", "toh"].

Without them, searches cover every source Open5e serves. Each result carries a source label (document key, title and ruleset), and lookups by name prefer the 2024 SRD, then the 2014 SRD. Character builds default to the 2024 SRD only (see ADR-008); pass ruleset: "5e-2014" or sources: ["srd-2014"] for the older rules. An unknown ruleset or document is an error. A build that mixes editions, e.g. sources: ["srd-2024", "open5e"], uses 2014 species and backgrounds the way the 2024 Player’s Handbook allows: the species keeps its traits, and ability increases come from the background. To add backgrounds without adding anything else, pass background_sources to generate_character_build, e.g. background_sources: ["toh"] for Tome of Heroes’ 19 backgrounds.

Universal search

Spells

Classes and species

Monsters

Equipment and items

Character options

Rules reference

DM tools

Player tools

Diagnostics

Development

npm run dev               # watch mode
npm run build             # compile to dist/
npm run lint              # eslint over src/
npm test                  # unit tests, no network (builds first)
npm run test:integration  # live Open5e API tests
npm run test:all          # both suites

Tests use Node’s built-in test runner. test/unit/ mocks fetch, so it runs offline and fast; test/integration/ exercises the real API and the real server process. See docs/testing.md.

Known quirks

• Duplicate names across books. A search for fireball returns every sourcebook’s Fireball, each labelled with its source. Detail lookups pick one (2024 SRD first); pass ruleset or sources to choose another.
• Uneven upstream filtering. Open5e ignores many filter parameters and returns the whole collection. The client sends only verified parameters and matches the rest locally; see docs/api-filters.md.
• Gaps in Open5e’s data are reported, not guessed. Examples: no 2014 SRD spell lists the Paladin, and some Tome of Heroes heritages have no source for their size. Look in a build’s warnings or a species’ resolved.unresolved.
• Builds are opinionated. Game rules (spell slots, hit points, ASIs) come from the SRD, but the scoring choices that pick a class, species or spell are judgment calls, collected in src/character-build/heuristics.ts. Multiclass builds are not supported; allow_multiclass: true is rejected.
• unified_search count vs items. For classes the reported count can exceed the number of returned items, because classes are listed whole and then ranked against the query.

Documentation

• docs/api-filters.md - per-endpoint Open5e filter support
• docs/testing.md - how the suites are organised
• docs/adr/ - architecture decision records
• docs/history/ - superseded point-in-time reports
• CLAUDE.md - guidance for Claude Code

Data source and licence

Content comes from the Open5e API, which serves material published under the OGL and Creative Commons licences. This server is MIT licensed; the game content it returns is governed by its own licences. Each item’s source names the document it comes from.