D&D Knowledge Navigator

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 claude_desktop_config.json file in your Claude Desktop configuration directory
   • Add the following configuration (adjust paths as needed):

     {
       "mcpServers": {
         "dnd": {
           "command": "/path/to/uv",
           "args": [
             "--directory",
             "/path/to/dnd-knowledge-navigator",
             "run",
             "dnd_mcp_server.py"
           ]
         }
       }
     }
     

4. Run the server:

   uv run python dnd_mcp_server.py
   

MCP Tool Usage

When connected to an AI assistant, the following tools are available:

• search_all_categories: Search across all D&D resources for specific terms
• verify_with_api: Verify D&D statements against official API data
• check_api_health: 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 TEMPLATES_ENABLED = 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")
• Fuzzy matching for common misspellings (e.g., "firball" → "fireball")
• Category prioritization to focus searches on relevant content

To disable query enhancement, set parameters in the enhance_query function to False.

Documentation

Comprehensive documentation is available in the docs/ directory:

• Usage Guide: How to use

... View full README on GitHub