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": "npx",
      "args": ["-y", "@frankvdb/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