procload/dnd-mcp

A Python-based server implementing the Model Context Protocol (MCP) that connects Claude and other AI assistants to Dungeons & Dragons 5e game information.
## What is MCP?
The Model Context Protocol (MCP) is a framework developed by Anthropic that enables AI assistants like Claude to communicate with external tools and services. This server leverages FastMCP, Anthropic's Python implementation of the protocol, to create a structured bridge between AI assistants and the D&D 5e API.
For a detailed explanation of MCP and how this project implements it, check out our blog article.
## Features
FastMCP Integration: Provides AI assistants with tools and resources to query D&D game data
D&D 5e API Integration: Complete access to spells, monsters, equipment, classes, races, and more
Efficient Caching: Persistent local storage of API responses for improved performance
Structured Data Access: Well-defined resources and tools for consistent AI interactions
Source Attribution: Comprehensive tracking and display of information sources
Visual Formatting: Markdown templates for beautiful presentation of D&D content
Query Enhancement: Intelligent processing of D&D queries with synonym handling and fuzzy matching
## Setup
### Prerequisites
Python 3.10 or higher
uv package manager (recommended)
Claude Desktop client (for using with Claude)
### Installation
1. Clone this repository:
git clone https://github.com/yourusername/dnd-knowledge-navigator.git
cd dnd-knowledge-navigator
2. Install dependencies:
uv pip install -r requirements.txt
or
pip install .
3. Configure Claude Desktop (if using with Claude):
Create a claudedesktopconfig.json file in your Claude Desktop configuration directory
Add the following configuration (adjust paths as needed):
json
"mcpServers": {
"dnd": {
"command": "/path/to/uv",
"args": [
"--directory",
"/path/to/dnd-knowledge-navigator",
"run",
"dndmcpserver.py"
4. Run the server:
uv run python dndmcpserver.py
## MCP Tool Usage
When connected to an AI assistant, the following tools are available:
searchallcategories: Search across all D&D resources for specific terms
verifywithapi: Verify D&D statements against official API data
checkapihealth: Check the health and status of the D&D 5e API
## Source Attribution System
The server includes a comprehensive source attribution system that:
Tracks the source of all information returned to the user
Provides confidence levels for each piece of information
Includes API endpoints and relevance scores
Formats attribution information for clear presentation
## Template System
The server includes a template system for formatting D&D content:
Monster stat blocks with organized attributes and abilities
Spell descriptions with formatted components and effects
Equipment details with organized properties
Configurable formatting options (tables, emojis, compact mode)
To disable templates, set TEMPLATESENABLED = False in src/templates/config.py.
## Query Enhancement System
The server includes a query enhancement system that improves search results:
Synonym handling for D&D terminology (e.g., "AC" → "armor class")
Special term recognition for game-specific notation (e.g., "2d6+3", "STR save")