D&D 5E MCP Server

An MCP (Model Context Protocol) server that provides access to D&D 5th Edition content via the Open5e REST API. This server enables AI assistants and other MCP clients to retrieve comprehensive D&D 5E information including spells, classes, races, monsters, and equipment.

Available Tools

Universal Search

• unified_search - Search across all D&D content types with intelligent ranking

  • Required query parameter for search terms

  • Optional content_types filter for specific content (spells, monsters, races, etc.)

  • Optional fuzzy_threshold for matching sensitivity

  • Returns ranked results across all content types

Spell Tools

• search_spells - Search for spells by name or retrieve all spells

  • Optional query parameter for filtering by spell name

  • Returns basic spell information (name, level, school, casting time, etc.)

• get_spell_details - Get comprehensive details about a specific spell

  • Requires spell_name parameter

  • Returns full spell description, components, duration, and class lists

• get_spell_by_level - Get all spells of a specific level (0-9)

  • Requires level parameter (0 for cantrips, 1-9 for spell levels)

• get_spells_by_class - Get all spells available to a specific class

  • Requires class_name parameter (e.g., "wizard", "cleric", "bard")

Class Tools

• search_classes - Get a list of all available D&D 5E classes

  • Returns basic information for all core classes

• get_class_details - Get detailed information about a specific class

  • Requires class_name parameter

  • Returns hit die, saving throws, description, and available subclasses

Race Tools

• search_races - Get a list of all available D&D 5E races

  • Returns basic race information from the lineage page

• get_race_details - Get detailed information about a specific race

  • Requires race_name parameter

  • Returns size, speed, ability score increases, traits, and description

Monster Tools

• search_monsters - Search for monsters with filtering options

  • Optional query parameter for monster names

  • Optional challenge_rating filter

  • Returns monster stats and basic information

• get_monsters_by_cr - Get all monsters of a specific challenge rating

• get_monsters_by_cr_range - Get monsters within a CR range for encounter planning

Equipment Tools

• search_weapons - Search for weapons with property filtering

  • Optional filters for martial/finesse weapons

• search_armor - Search for armor with AC and category filtering

• search_magic_items - Search for magic items with rarity filtering

• get_magic_item_details - Get detailed magic item information

Character Building Tools

• search_feats - Search for character feats

• get_feat_details - Get detailed feat information

• search_backgrounds - Search for character backgrounds

• get_background_details - Get detailed background information

• generate_character_build - Generate optimized character builds

• compare_character_builds - Compare multiple character build options

• get_build_recommendations - Get build recommendations for party composition

Dungeon Master Tools

• build_encounter - Build balanced encounters for specified party

  • Requires party_size, party_level, and difficulty

  • Optional filters for environment, monster types, CR range

  • Returns balanced encounter with XP calculations

• calculate_encounter_difficulty - Calculate difficulty of custom encounters

  • Requires party info and list of monsters with counts

  • Returns encounter difficulty rating and XP breakdown

Rules & Reference Tools

• search_conditions - Search for status conditions and effects

• get_condition_details - Get detailed condition information

• get_all_conditions - Get all conditions for quick reference

• search_sections - Search rules sections for quick rule lookups

• get_section_details - Get detailed rules section information

• search_spell_lists - Search spell lists by class

• get_spell_list_details - Get detailed spell list for specific classes

Installation

1. Clone this repository:

   git clone <repository-url>
   cd dnd-mcp

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Usage

Running the Server

npm start

Development Mode

npm run dev

MCP Client Configuration

Add to your MCP client configuration (e.g., mcp.json):

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

Example MCP Tool Usage

The server implements the Model Context Protocol, exposing tools that can be called by MCP clients. Here are some example tool calls:

Universal Search

{
  "name": "unified_search",
  "arguments": {
    "query": "fireball",
    "content_types": ["spells", "magic-items"]
  }
}

Build Encounter

{
  "name": "build_encounter",
  "arguments": {
    "party_size": 4,
    "party_level": 5,
    "difficulty": "medium",
    "environment": "dungeon"
  }
}

Generate Character Build

{
  "name": "generate_character_build",
  "arguments": {
    "playstyle": "damage",
    "preferred_class": "fighter",
    "campaign_type": "combat"
  }
}

Technical Features

• Intelligent Caching: 1-hour TTL cache to minimize requests to source website

• Rate Limiting: 1-second delays between requests to respect server resources

• Error Handling: Comprehensive error handling for network issues and missing content

• TypeScript: Fully typed implementation for better development experience

• MCP Protocol: Full compliance with Model Context Protocol specifications

• Comprehensive Testing: Full test coverage for Open5e API functionality and scraping operations

Architecture

• Open5e API Integration: Uses Axios for REST API communication with Open5e

• Content Processing: Structured data handling from Open5e JSON responses

• MCP Server: Standard MCP protocol implementation with stdio transport

• Caching Layer: NodeCache for efficient content storage

Development

Available Scripts

• npm run build - Compile TypeScript to JavaScript

• npm run dev - Run in development mode with hot reload

• npm start - Run the built server

• npm run lint - Run ESLint

• npm test - Run Jest tests (includes comprehensive Open5e API tests)

Project Structure

src/
├── index.ts      # MCP server implementation and tool handlers
├── scraper.ts    # Open5e API integration and data fetching
tsconfig.json     # TypeScript configuration
mcp.json         # MCP client configuration example

Data Sources

This server uses the Open5e REST API to access D&D 5th Edition content. The implementation:

• Leverages the Open5e API for comprehensive D&D 5E data

• Implements intelligent caching to minimize API requests

• Uses appropriate rate limiting and error handling

• Provides structured JSON responses from the API

Recent Updates

• Open5e Migration: Migrated from web scraping to Open5e REST API for better reliability

• Comprehensive Tool Suite: Added 40+ tools covering all D&D 5E content types

• Unified Search: Intelligent search across all content with fuzzy matching

• DM Tools: Encounter building, difficulty calculation, and party balancing

• Character Building: Automated character optimization and build comparison

• Full Test Coverage: Comprehensive testing for all API functionality

License

MIT License