mnehmos.open5e.mcp

MCP server for Open5e - Query D&D 5e game data and contribute to the open-source database

A dual-mode MCP server that provides:

• Consumer Mode: Query spells, monsters, items, conditions, and more from 22+ source books
• Contributor Mode: Validate entries, check for collisions, diff against live API, and generate PR-ready JSON
• RAG Developer Chatbot: Search and chat with Open5e repository documentation

Features

Installation

npm

npm install -g mnehmos.open5e.mcp

From Source

git clone https://github.com/Mnehmos/mnehmos.open5e.mcp.git
cd mnehmos.open5e.mcp
npm install
npm run build

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mnehmos.open5e.mcp": {
      "command": "node",
      "args": ["path/to/mnehmos.open5e.mcp/dist/index.js"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "mnehmos.open5e.mcp": {
      "command": "mnehmos-open5e-mcp"
    }
  }
}

Quick Start

Search for Spells

Search: "fireball"
→ Returns Fireball, Delayed Blast Fireball from multiple sources

Get a Monster

Get: monsters/goblin
→ Full stat block with AC, HP, abilities, actions, environments

Validate a Contribution

Validate: { name: "Custom Spell", level: 3, school: "Evocation", ... }
→ Errors for missing required fields
→ Suggestions for slug format
→ Warnings for unusual values

Tool Reference

Consumer Tools

#### search Search across all Open5e resources with optional filters.

search({
  query: "fireball",
  resource_type: "spells",      // optional: spells, monsters, items, etc.
  document_slug: "srd-2014",    // optional: filter by source book
  limit: 10                     // optional: max results (default 20)
})

Returns results with slug, key (for v2 resources), name, excerpt, and web_url.

#### get Fetch a single resource by slug. Auto-tries common document prefixes for v2 resources.

// Simple slug - auto-discovers the full key
get({ resource_type: "spells", slug: "fireball" })
// → Finds srd-2024_fireball or srd-2014_fireball

// Full key - direct lookup
get({ resource_type: "spells", slug: "srd-2014_fireball" })

#### list List resources with filters (pagination supported).

list({
  resource_type: "monsters",
  cr: 3,                        // Challenge Rating
  document_slug: "wotc-srd",    // Source book
  type: "Dragon",               // Creature type
  limit: 20,
  offset: 0
})

list({
  resource_type: "spells",
  level: 3,                     // Spell level (0-9)
  school: "Evocation",          // Spell school
  document_slug: "srd-2014"
})

#### batch_get Fetch multiple resources in parallel (max 50).

batch_get({
  requests: [
    { resource_type: "monsters", slug: "goblin" },
    { resource_type: "monsters", slug: "kobold" },
    { resource_type: "conditions", slug: "blinded" }
  ]
})

#### list_documents List all available source books.

list_documents()
// → srd-2014, srd-2024, tob, tob2, tob3, a5e-ag, bfrd, etc.

#### list_endpoints List all API endpoints with version info.

list_endpoints()
// → spells (v2), monsters (v1), conditions (v2), etc.

Contributor Tools

#### validate_entry Validate a draft entry against Open5e schema.

validate_entry({
  resource_type: "spells",
  data: {
    name: "Test Spell",
    slug: "test-spell",
    level: 3,
    school: "Evocation",
    // ... other fields
  },
  strict: false  // optional: fail on warnings
})

Returns:

• valid: boolean
• errors: Array of schema violations
• warnings: Unusual but valid values
• suggestions: Helpful hints (slug format, valid enums)

#### check_slug Check if a slug exists or would collide.

check_slug({
  resource_type: "monsters",
  slug: "goblin",
  document_slug: "wotc-srd",     // optional
  original_slug: "goblin-old"    // optional: detect mutations
})

Returns:

• exists: boolean
• is_mutation: boolean (slug changed from original)
• collision_risk: "none" | "same_document" | "different_document"
• existing_entry: Details if exists

#### diff Compare a draft entry against the live API version.

diff({
  resource_type: "monsters",
  slug: "goblin",
  draft: {
    name: "Goblin",
    hit_points: 10,  // Changed from 7
    // ... partial or full entry
  },
  ignore_fields: ["page_no"]  // optional
})

Returns field-by-field diff with type: "added" | "removed" | "modified".

#### normalize Clean up and standardize entry data.

normalize({
  resource_type: "spells",
  data: {
    name: "test   spell",
    desc: "A   spell   with   bad   spacing.\n\nAnd extra   newlines."
  },
  options: {
    fix_whitespace: true,
    fix_markdown: true,
    standardize_names: true,
    generate_slug: true
  }
})

#### generate_pr_json Generate PR-ready JSON with file path and checklist.

generate_pr_json({
  resource_type: "spells",
  document_slug: "srd-2014",
  operation: "add",  // or "modify"
  data: { /* validated entry */ }
})

Returns:

• json_output: Formatted JSON string
• file_path: Where to place the file (e.g., data/srd-2014/spells/test-spell.json)
• validation: Pre-flight validation results
• checklist: PR submission checklist

RAG Tools

The RAG tools connect to the Open5e Developer Chatbot, which indexes the entire open5e-api and open5e (frontend) repositories.

#### rag_health Check RAG service status.

rag_health()
// → { healthy: true, chunks: 484, vectors: 484, sources: 214 }

#### rag_stats Get index statistics.

rag_stats()
// → Project info, chunk/vector counts, embedding status

#### rag_sources List all indexed sources with GitHub URLs.

rag_sources()
// → README.md, CONTRIBUTING.md, AGENTS.md, models/*.py, views/*.py, etc.

#### rag_search Search repository documentation.

rag_search({
  query: "how to add a new monster",
  mode: "hybrid",    // semantic, keyword, or hybrid
  top_k: 5
})

Returns chunks with scores, source URLs, and positions.

#### rag_chat Chat with AI about Open5e development.

rag_chat({
  message: "How do I add a new monster to the Open5e database?",
  history: [],  // optional: conversation history
  top_k: 5      // optional: context chunks
})

Returns detailed answer with source citations.

Meta Tools

#### health_check Check API connectivity and cache status.

health_check()
// → { api_reachable: true, api_latency_ms: 628, cache_status: {...}, version: "0.1.0" }

Available Source Books

Use list_documents() for the complete list.

Resource Types

Usage Patterns

Game Master: Building an Encounter

// Find CR 3 monsters from the SRD
const monsters = await list({
  resource_type: "monsters",
  cr: 3,
  document_slug: "wotc-srd"
});

// Get full details for selected monsters
const details = await batch_get({
  requests: monsters.results.slice(0, 5).map(m => ({
    resource_type: "monsters",
    slug: m.slug
  }))
});

Contributor: Adding a New Spell

// 1. Draft the spell
const draft = {
  name: "Arcane Bolt",
  slug: "arcane-bolt",
  level: 0,
  school: "Evocation",
  casting_time: "1 action",
  range: "120 feet",
  verbal: true,
  somatic: true,
  material: false,
  concentration: false,
  ritual: false,
  duration: "Instantaneous",
  desc: "You hurl a bolt of arcane energy at a creature...",
  document__slug: "homebrew"
};

// 2. Validate
const validation = await validate_entry({
  resource_type: "spells",
  data: draft
});

// 3. Check for collisions
const slugCheck = await check_slug({
  resource_type: "spells",
  slug: "arcane-bolt"
});

// 4. Generate PR JSON
const prData = await generate_pr_json({
  resource_type: "spells",
  document_slug: "homebrew",
  operation: "add",
  data: draft
});

Learning: Understanding the Codebase

// Search for how monsters are modeled
const results = await rag_search({
  query: "Monster model fields actions abilities",
  top_k: 5
});

// Ask the chatbot
const answer = await rag_chat({
  message: "What fields are required for a monster entry in v1?"
});

Integration

rpg-mcp

This server is designed to integrate with rpg-mcp for live creature lookups during gameplay:

// Replace hardcoded creature presets with Open5e lookups
const creature = await open5e.get({
  resource_type: "monsters",
  slug: "adult-red-dragon"
});

Quest Keeper AI

Surface contributor workflows in the Quest Keeper AI frontend for community content creation.

Development

Setup

npm install
npm run build

Testing

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Scripts

Project Structure

src/
├── index.ts          # MCP server entry point, tool registration
├── types.ts          # Shared TypeScript types
├── api/              # Open5e API client
├── cache/            # Response caching
├── contributor/      # Validation, diff, PR generation
├── schema/           # Zod schemas for all resource types
└── utils/            # Helpers, slug handling

API Reference

• Open5e API: https://api.open5e.com
• API Documentation: https://open5e.com/api-docs
• GitHub Repository: https://github.com/open5e/open5e-api
• Discord: https://discord.gg/9RNE2rY

Contributing

1. Fork the repository
2. Create a feature branch
3. Run tests: npm test
4. Submit a pull request

License

MIT © Mnehmos

Part of the Mnehmos MCP ecosystem

• mnehmos.ooda.mcp - File system and shell operations
• mnehmos.synch.mcp - Agent memory and handoffs
• rpg-mcp - RPG game engine