Skip to main content
Glama

Tests Version Install in Claude Desktop

A complete D&D 5e reference and utility MCP server backed by live 5etools data.

Quick Start

Prerequisite: Node.js ≥ 22 must be your system's default node. Claude Desktop uses the macOS launch environment PATH, not your shell session — your terminal's active nvm version doesn't apply. If you use nvm, run nvm alias default 22 (or nvm install 22 && nvm alias default 22 if you don't have it) and fully quit and relaunch Claude Desktop. If you don't use nvm, install Node.js from nodejs.org.

  1. Download 5eMCP.mcpb from the latest release

  2. Open the file — Claude Desktop will prompt you to install it, or go to Settings → Extensions → Install Extension and select the file

  3. Enter your GitHub personal access token when prompted (required — create a free one at github.com/settings/tokens with public_repo scope or read-only access to public repos)

  4. Choose your default ruleset (2024 or 2014)

  5. Restart Claude Desktop

Your token is stored securely in the OS keychain (macOS Keychain / Windows Credential Manager) — never in plain text.


Developers (Claude Code, Cursor, manual config)

Requirements: Node.js ≥ 22, optional GitHub personal access token (read-only, public repos)

git clone https://github.com/jazzsequence/5eMCP.git
cd 5eMCP
npm install
npm run build
pwd   # copy this — you'll use it as your path in the config below

In the configs below, replace /path/to/5eMCP with the output of pwd above (e.g. /Users/you/Projects/5eMCP).

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "5etools": {
      "command": "node",
      "args": ["/path/to/5eMCP/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "DEFAULT_RULESET": "2024"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "5etools": {
      "command": "node",
      "args": ["/path/to/5eMCP/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "DEFAULT_RULESET": "2024"
      }
    }
  }
}

Claude Desktop (manual config) {#claude-desktop-manual-config}

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "5etools": {
      "command": "node",
      "args": ["/path/to/5eMCP/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "DEFAULT_RULESET": "2024"
      }
    }
  }
}

DEFAULT_RULESET can be "2024" (default) or "2014" for legacy rules. GITHUB_TOKEN is optional but strongly recommended — unauthenticated requests are rate-limited to 60/hr.

Related MCP server: D&D 5E MCP Server

How It Works

5e.tools is fully client-side. When spells.html loads, the browser fetches data/spells/spells-phb.json directly from GitHub and renders it in JavaScript. This server replicates that pattern server-side:

GitHub Contents API
  → manifest: { spells: [...], bestiary: [...], book: [...], ... }
  → SHA-keyed disk/Redis cache
  → raw.githubusercontent.com (fetch on miss)
  → translation layer (resolve {@tags}, merge fluff, normalize)
  → MCP tool response

The manifest is schema-agnostic and self-updating. When 5etools adds a new content type, the next manifest refresh picks it up automatically — no code change required. Unknown types run through the passthrough handler (tags resolved, internal fields stripped) and return clean JSON. Nothing is ever inaccessible.

Available Tools

Meta Tools

Tool

Description

help

Full decision guide to every tool — call first when unsure which one to use.

manifest_status

Build time, file counts by type, unknown types discovered.

list_sources

All source abbreviations with content types.

fetch_content

Fetch and translate any file in the manifest by content type + file name. Universal fallback for any content type.

Search Tools (*_search)

All search tools accept query (name substring), ruleset ("2024" or "2014"), limit, fields (optional list of field names to include in each result — default is all fields, e.g. ["name","cr","source"]), and include_homebrew (boolean, default false — when true also searches TheGiddyLimit/homebrew alongside official results). Results match on name, source abbreviation, pantheon/setting, and any top-level array-of-strings field in the data (e.g. damageInflict, conditionInflict, environment, property tags like "Vst|EGW").

Selected tools support additional structured filter parameters:

Tool

Extra Parameters

spell_search

level (int 0–9), school (full name: evocation, necromancy, etc.)

monster_search

type (beast, humanoid, undead…), cr_max (max CR inclusive: "1/4", "1/2", "5"…), environment (habitat substring: "underdark", "forest", "nine hells"…)

item_search

rarity (common, uncommon, rare, very rare, legendary, artifact), type (weapon, armor, wondrous…)

classfeature_search

class_name (e.g. "Wizard"), level (int 1–20)

subclassfeature_search

class_name (e.g. "Wizard"), subclass_name (e.g. "Abjurer"), level (int 1–20)

Tool

Content

spell_search

Spells

monster_search

Monsters and creatures

item_search

Magic and mundane items

race_search

Playable species / races

background_search

Character backgrounds

feat_search

Feats

condition_search

Conditions and diseases

vehicle_search

Vehicles and vessels

object_search

Objects

trap_search

Traps and hazards

psionic_search

Psionic powers and disciplines

deck_search

Decks (e.g. Deck of Many Things)

reward_search

Supernatural gifts and boons

optfeature_search

Optional class features and invocations

table_search

Random tables

variantrule_search

Variant rules

deity_search

Deities and gods (searchable by pantheon/setting)

language_search

Languages

skill_search

Skills

sense_search

Senses (darkvision, tremorsense, etc.)

book_search

Sourcebooks (name, ID, source, publication date)

adventure_search

Published adventures

class_search

Character classes (official + homebrew)

subclass_search

Subclasses and archetypes

classfeature_search

Class features (searchable by class and level)

subclassfeature_search

Subclass features (searchable by class, subclass, and level)

Get Tools (*_get)

Exact lookup by name with full fluff/description merged in. Accept name, optional source, and ruleset.

Tool

Content

spell_get

Full spell entry with description

monster_get

Full stat block with lore

item_get

Full item entry with description

race_get

Full race entry with traits and fluff

background_get

Full background entry with fluff

feat_get

Full feat entry

book_get

Sourcebook metadata by name

adventure_get

Adventure metadata by name

class_get

Full class entry by name

subclass_get

Full subclass entry by name

Sourcebook & Adventure Content

Tool

Description

book_content_get

Retrieve full prose from a sourcebook or adventure by source abbreviation (e.g. SCC, EGW, SCC-CK). Without section: returns a table of contents. With section only: returns that section's subsection names, or its full text if it has no subsections. With section + subsection: returns that subsection's text rendered as clean markdown. Matching is case-insensitive substring throughout.

Omnisearch

Tool

Description

omnisearch

Search all 24 content types at once. Returns results tagged with entityType. Accepts include_homebrew (default true — homebrew is included by default).

DM Calculator Tools

All calculators are purely local — no network calls, no API key needed.

Tool

Description

cr_calculate

Calculate a monster's Challenge Rating from its stats (HP, AC, DPR, attack bonus). Applies DMG Appendix B algorithm. Supports damage immunity (effective HP ×2), resistance (×1.5), and vulnerability (×0.5). Returns final CR, XP, and the defensive/offensive sub-CRs.

cr_scale

Look up the expected stat ranges (HP, AC, attack bonus, DPR, save DC, proficiency bonus) for a given CR from the DMG reference table. Useful for designing or adjusting homebrew monsters.

encounter_build

Evaluate encounter difficulty for a party vs a set of monsters. Supports both 2014 (easy/medium/hard/deadly, with monster-count XP multiplier) and 2024 (low/moderate/high, no multiplier) rulesets. Returns adjusted XP, difficulty label, and full threshold breakdown.

loot_generate

Generate individual treasure loot for a monster by CR, using the DMG individual treasure tables. Returns all possible outcomes for the CR bracket with probability percentages and average coin amounts.

Session Guidance

The server declares an instructions string on the MCP initialize handshake — a condensed tool decision guide (which tool to reach for, ruleset/homebrew defaults, class feature lookups, calculators). Spec-compliant clients fold this into context automatically on connect, with no user action required. This is what actually reaches Claude Desktop, since Desktop doesn't expose MCP-registered prompts as an invokable command the way Claude Code does.

The same content is also registered as an MCP prompt named 5eMCP, for clients that support explicit prompt invocation — in Claude Code this shows up as /mcp__<server-name>__5eMCP (using whichever key you gave the server in your mcpServers config, e.g. 5etools per the examples above). There's also a help tool with the same guidance, callable like any other tool from clients (including Claude Desktop) that don't support MCP prompts at all.

Environment Variables

Variable

Default

Description

GITHUB_TOKEN

—

Read-only GitHub PAT. Strongly recommended.

DEFAULT_RULESET

"2024"

Which ruleset to use ("2024" or "2014").

MANIFEST_TTL_SECONDS

3600

How often to rebuild the manifest (seconds).

CACHE_DIR

~/.cache/5emcp

Disk cache location (local stdio mode).

REDIS_URL

—

Redis connection URL (e.g. redis://localhost:6379). When set and reachable, Redis is used instead of disk cache. Falls back to disk on connection failure.

LOCAL_BASE_URL

—

Base URL of a self-hosted 5etools static mirror (e.g. https://5e.example.com). When set, spell/monster/item/etc. content for the 2024 and 2014 ruleset repos is fetched from this mirror instead of raw.githubusercontent.com — faster, no GitHub rate limit for content fetches. Ignored if LOCAL_DATA_DIR is also set. Manifest indexing (file listing) still uses the GitHub Contents API, since a static mirror has no equivalent listing endpoint. Homebrew content is never redirected.

LOCAL_DATA_DIR

—

Filesystem path to a local 5etools data/ directory (e.g. /opt/5etools/data) — typically used when the MCP server runs colocated with a self-hosted mirror. When set, both manifest indexing and content fetching read directly from disk, bypassing GitHub entirely for core ruleset content (no rate limit, no network round-trip at all). Homebrew still goes through the GitHub Contents API regardless, since self-hosted mirrors don't bundle it — that call degrades gracefully (logged, non-fatal) if it hits a rate limit. Assumes the directory matches the ruleset(s) you query; a single local mirror generally only reflects one ruleset.

PORT

3000

Port for the HTTP transport (npm start / dist/http.js).

MCP_HTTP_TOKEN

—

Bearer token required on the HTTP transport's /mcp endpoint. If unset, the endpoint is unauthenticated — fine on a private network, not recommended for public exposure.

HTTP Transport

In addition to stdio (used by Claude Desktop/Code/Cursor above), the server supports the MCP Streamable HTTP transport, useful for running the server remotely (e.g. colocated with a self-hosted 5etools mirror) and connecting to it from clients that can't spawn a local process.

Colocated with a self-hosted mirror (reads the mirror's data/ directory straight off disk — fastest, no GitHub calls for core content):

LOCAL_DATA_DIR=/opt/5etools/data MCP_HTTP_TOKEN=your-secret npm start

Or pointing at a mirror over HTTP (e.g. the MCP server runs elsewhere than the mirror):

LOCAL_BASE_URL=https://5e.example.com MCP_HTTP_TOKEN=your-secret npm start

npm start runs the TypeScript source directly via tsx — no separate build step needed. If you do want a compiled build (e.g. for npm run build:mcpb), note that tsc is memory-hungry; on RAM-constrained hosts it can OOM, in which case npm start is the way to go anyway.

This starts a stateless HTTP server:

  • POST /mcp — MCP JSON-RPC endpoint (Streamable HTTP transport, one server instance per request)

  • GET /health — health check, returns {"status":"ok","service":"5eMCP"}

If MCP_HTTP_TOKEN is set, requests to /mcp must include Authorization: Bearer <token>; /health is always open.

Connecting Claude Desktop / claude.ai to a Remote Instance

Once the HTTP server is deployed and reachable, connect to it as a Custom Connector rather than editing claude_desktop_config.json — that file is for stdio servers that Claude spawns as a local process, which doesn't apply to a server running elsewhere:

  1. Claude Desktop (or claude.ai) → Settings → Connectors → Add custom connector

  2. Enter your server's URL, e.g. https://5emcp.example.com/mcp

  3. Click Add

If MCP_HTTP_TOKEN is unset, that's all — the connector works immediately. Note that the Custom Connector UI's "Advanced settings" are built for OAuth (Client ID/Secret), not a raw static bearer token, so MCP_HTTP_TOKEN isn't directly pluggable there. If you need auth on a Custom Connector, put a reverse proxy in front (e.g. Cloudflare Access, Caddy with basicauth) rather than relying on MCP_HTTP_TOKEN alone.

Ruleset Support

Most tools accept ruleset: "2024" | "2014":

  • "2024" → 5etools-mirror-3/5etools-src (current rules)

  • "2014" → 5etools-mirror-3/5etools-2014-src (legacy rules)

Exceptions: cr_calculate, cr_scale, and loot_generate are ruleset-agnostic (the DMG reference tables they use don't differ by edition) — of the DM calculators, only encounter_build takes a ruleset param. help takes no parameters at all.

Development

npm run dev          # Run without compile step (tsx)
npm run build        # Compile TypeScript
npm run typecheck    # Type-check without emitting
npm test             # Run tests (Vitest)
npm run lint         # ESLint

This project uses TDD. Tests are written before implementation. See AGENTS.md for the full workflow including mandatory reviewer agent approval before commits.

# First-time setup: install git hooks
./.githooks/install.sh

Architecture

flowchart TD
    Client["MCP Client\n(Claude Desktop / Claude Code / Cursor)"]
    Server["MCP Server (Node.js)"]
    Manifest["Manifest Layer\n1-hour TTL refresh"]
    Cache["Cache Layer\nSHA-keyed disk or Redis"]
    Translation["Translation Layer\ntag resolver · typed handlers · passthrough"]
    Calculators["Calculators\nCR · encounter · loot · scaling"]
    GH["GitHub Contents API"]
    Raw["raw.githubusercontent.com"]
    Redis[("Redis / Disk")]

    Client -->|stdio| Server
    Server --> Manifest
    Server --> Cache
    Server --> Translation
    Server --> Calculators
    Manifest -->|"index all files"| GH
    Cache -->|"fetch on miss"| Raw
    Cache <-->|"read / write"| Redis

5etools data is fetched live from public GitHub repositories. This server does not store or redistribute any content. The GitHub API rate limit applies. A GitHub token is required for sustained use.

Calculator logic is ported from 5etools' MIT-licensed JavaScript source.

Credits

D20 icon by Delapouite via game-icons.net, licensed CC BY 3.0.

Available Tools

46 tools
adventure_getA

Get a specific D&D 5e published adventure by exact name. Returns the complete entry with description merged in. Prefer this over adventure_search when you have an exact name.

Inputs: name (required), source, ruleset.

background_getA

Get a specific D&D 5e character background by exact name. Returns the complete entry with description merged in. Prefer this over background_search when you have an exact name.

Inputs: name (required), source, ruleset.

book_content_getA

Get content from a D&D 5e sourcebook or adventure by source abbreviation (e.g. SCC, EGW, PHB). Uses a drill-down navigation model to minimise token usage — fetch only what you need:

  1. Omit section → returns top-level section/chapter names (TOC).

  2. Provide section only → if the section has subsections, returns their names; if it is a leaf (no subsections), returns its full text.

  3. Provide section + subsection → returns the rendered text of just that subsection.

  4. Not found → returns an error and the available names at that level. Supports book sources (PHB, DMG, SCC, EGW…) and adventure content (SCC-CK, COS…). Section and subsection filters are case-insensitive substring matches.

Inputs: source (required), ruleset, section, subsection.

book_getA

Get a specific D&D 5e sourcebook by exact name. Returns the complete entry with description merged in. Prefer this over book_search when you have an exact name.

Inputs: name (required), source, ruleset.

class_getA

Get a D&D 5e character class by exact name. Returns the full class entry plus a resolvedFeatures array containing the complete text of every class feature at each level — no reference strings, actual feature descriptions. The ruleset param selects the correct edition: '2024' returns the 2024 XPHB version (e.g. XPHB Wizard), '2014' returns the classic PHB version. For features at a specific level use classfeature_search. For subclass details use subclass_get or subclassfeature_search.

Inputs: name (required), source, ruleset.

cr_calculateA

Calculate the Challenge Rating (CR) for a custom monster given its defensive and offensive stats. Uses the DMG Appendix B algorithm: defensive CR is derived from HP (adjusted for damage immunity, resistance, or vulnerability) and AC; offensive CR is derived from DPR and attack bonus (or save DC). The two are averaged to produce the final CR. Provide at least one of attackBonus or saveDc for the offensive calculation.

Inputs: ac (required), hp (required), dpr (required), saveDc, +4 more.

cr_scaleA

Look up the expected stat ranges for a given Challenge Rating from the DMG reference table. Returns proficiency bonus, expected AC, HP range, attack bonus, DPR range, and save DC. Useful for scaling a homebrew monster up or down to a target CR, or for quickly checking whether a monster's stats are appropriate for its intended CR.

Inputs: cr (required).

encounter_buildA

Evaluate the difficulty of a D&D 5e encounter given the party composition and monster CRs. Supports both 2014 (classic) and 2024 (one D&D) rulesets. 2014 mode: uses four difficulty tiers (easy/medium/hard/deadly) with a monster count XP multiplier. 2024 mode: uses three difficulty tiers (low/moderate/high) with no multiplier. Both modes add a 'trivial' tier below easy/low and an 'absurd' tier above deadly/high. Returns total XP, adjusted XP (2014 only), difficulty label, and full threshold breakdown.

Inputs: monsterCrs (required), partyLevels (required), ruleset.

feat_getA

Get a specific D&D 5e feat by exact name. Returns the complete entry with description merged in. Prefer this over feat_search when you have an exact name.

Inputs: name (required), source, ruleset.

fetch_contentA

Fallback tool — fetch any file in the manifest by content type and file name. Prefer the typed _search and _get tools (spell_search, monster_get, class_get, etc.) when available. Use fetch_content for content types that don't have a typed tool, or when you need raw file access. Omit file_name to list available files for a content type. Returns tag-resolved, metadata-stripped JSON.

Inputs: content_type (required), ruleset, homebrew, file_name.

helpA

Returns a guide to all available 5eMCP tools and when to use each. Call this first when unsure which tool to reach for — it explains the decision between omnisearch vs typed search vs _get tools, class feature lookups, book content, DM calculators, and the fetch_content fallback.

Inputs: no named parameters.

item_getA

Get a specific D&D 5e magic or mundane item by exact name. Returns the complete entry with description merged in. Prefer this over item_search when you have an exact name.

Inputs: name (required), source, ruleset.

list_sourcesA

List all available source abbreviations with their content types and files. Optionally filter by content type.

Inputs: ruleset, homebrew, content_type.

loot_generateA

Generate individual treasure loot for a monster of a given Challenge Rating, based on the DMG individual treasure tables. Returns all possible outcomes for the appropriate CR bracket (Challenge 0-4, 5-10, 11-16, or 17+) with their d100 range, probability percentage, and average coin amounts (using dice average values). Roll a d100 to select a row, or use the average coins for a quick reference.

Inputs: cr (required).

manifest_statusA

Returns the manifest build time, file counts by content type, and any unknown content types (those without typed handlers).

Inputs: ruleset.

monster_getA

Get a specific D&D 5e monster or creature by exact name. Returns the complete entry with description merged in. Prefer this over monster_search when you have an exact name.

Inputs: name (required), source, ruleset.

omnisearchA

Search across ALL D&D 5e content types simultaneously — spells, monsters, items, classes, subclasses, feats, races, backgrounds, conditions, and more. Start here when you don't know what type of content you need. Each result includes an entityType field so you can tell what kind of thing was found. For deeper filtering within a single type, follow up with the typed _search tool (e.g. spell_search, monster_search). Homebrew is included by default.

Inputs: query (required), ruleset, per_type_limit, include_homebrew.

race_getA

Get a specific D&D 5e playable species or race by exact name. Returns the complete entry with description merged in. Prefer this over race_search when you have an exact name.

Inputs: name (required), source, ruleset.

spell_getA

Get a specific D&D 5e spell by exact name. Returns the complete entry with description merged in. Prefer this over spell_search when you have an exact name.

Inputs: name (required), source, ruleset.

subclass_getA

Get a specific D&D 5e subclass or archetype by exact name. Returns the complete entry with description merged in. Prefer this over subclass_search when you have an exact name.

Inputs: name (required), source, ruleset.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 46 tools

    Disambiguation4/5

    Typed _search and _get tools target distinct content types, and help/omnisearch explicitly guide fallback when the type is unknown. Some ambiguity remains between similar types (item/object/vehicle, book_get/book_content_get, classfeature vs subclassfeature), but descriptions mostly resolve it.

    Naming Consistency4/5

    All tool names are snake_case and mostly follow a predictable contenttype_search/contenttype_get suffix pattern. Deviations like omnisearch, list_sources, manifest_status, and book_content_get are readable but prevent perfect uniformity.

    Tool Count2/5

    At 46 tools, the set is excessive for an MCP server; many are near-identical search wrappers differing only by content type. These could largely be consolidated behind omnisearch or a typed search parameter, reducing selection overhead.

    Completeness4/5

    The surface covers a wide range of D&D 5e content types plus raw fetch fallback, book drill-down, and DM calculators. Minor gaps include missing typed _get counterparts for several search-only types, but fetch_content helps compensate.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides fast, cached access to comprehensive Dungeons & Dragons 5th Edition data including spells, monsters, classes, races, equipment, and rules through Open5e and D\&D 5e APIs.
      7
      2
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Provides comprehensive access to Dungeons & Dragons 5th Edition content through the Open5e API. It enables users to search for game mechanics, generate character builds, and create balanced encounters via natural language.
      37
      22
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only SRD lookup and deterministic enrichment tools for D&D 5e content generation, including search, entity retrieval, and generation of monsters, spells, items, NPCs, and encounters.
      MIT