5eMCP

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

Quick Start

Claude Desktop — One-Click Install (recommended)

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

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:

Get Tools (*_get)

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

Sourcebook & Adventure Content

Omnisearch

DM Calculator Tools

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

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

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

Legal

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.