dnd-mcp

DND MCP Server

Install

npx -y dnd-mcp-server

README.md

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

Tool	Description	Required
`unified_search`	Search across all D&D content types (spells, monsters, items, races, classes, etc.) with intelligent ranking and filtering	`query`

Spells

Tool	Description	Required
`search_spells`	Search spells by name, level, school or class list	-
`get_spell_details`	Get detailed information about a specific D&D 5E spell	`spell_name`
`get_spell_by_level`	Get all spells of a specific level	`level`
`get_spells_by_class`	Get the spells on a class's spell list, lowest level first; filter by `level` or `max_level`	`class_name`

Classes and species

Tool	Description	Required
`search_classes`	List D&D 5E base classes with their features and subclass names	-
`get_class_details`	Get a class: hit die, proficiencies, features by level, spell slots and subclasses with their features	`class_name`
`search_races`	Search species, including subspecies whose names omit the parent (Lightfoot for Halfling)	-
`get_race_details`	Get a species with what it inherits resolved: size, speed, combined ability increases, parent traits	`race_name`

Monsters

Tool	Description	Required
`search_monsters`	Search monsters by name, challenge rating, type or environment	-
`get_monsters_by_cr`	Get monsters by challenge rating	`challenge_rating`
`get_monsters_by_cr_range`	Get monsters within a challenge rating range, optionally by environment and type	`min_cr, max_cr`

Equipment and items

Tool	Description	Required
`search_weapons`	Search for D&D 5E weapons with property filtering	-
`search_magic_items`	Search magic items by name, rarity, category or attunement	-
`get_magic_item_details`	Get detailed information about a specific D&D 5E magic item	`item_name`
`search_armor`	Search for D&D 5E armor with filtering options	-
`get_armor_details`	Get detailed information about a specific D&D 5E armor	`armor_name`

Character options

Tool	Description	Required
`search_feats`	Search for D&D 5E feats with filtering options	-
`get_feat_details`	Get detailed information about a specific D&D 5E feat	`feat_name`
`search_backgrounds`	Search for D&D 5E character backgrounds with filtering options	-
`get_background_details`	Get detailed information about a specific D&D 5E background	`background_name`

Rules reference

Tool	Description	Required
`search_conditions`	Search for D&D 5E conditions and status effects	-
`get_condition_details`	Get a condition, with its wording for the requested ruleset	`condition_name`
`get_all_conditions`	Get all D&D 5E conditions for quick reference	-
`search_sections`	Search rules sections by name or text	-
`get_section_details`	Get a rules section by name or key	`section_name`
`get_all_sections`	List every rules section by name, key and chapter, without the text	-

DM tools

Tool	Description	Required
`build_encounter`	Build a balanced encounter for a party, sampling monsters from the whole CR range	`party_size, party_level, difficulty`
`calculate_encounter_difficulty`	Calculate the difficulty of a custom encounter with specific monsters	`party_size, party_level, monsters`

Player tools

Tool	Description	Required
`generate_character_build`	Generate a build: species, class and subclass, background, ability scores, hit points, spells, feats and a level-by-level plan	-
`compare_character_builds`	Generate and compare multiple character builds with different options	`build_options`
`get_build_recommendations`	Get character build recommendations based on party composition and campaign needs	`existing_party, campaign_type`

Diagnostics

Tool	Description	Required
`get_api_stats`	Get API performance and caching statistics	-

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.