Servidor MCP de D&D 5E
Un servidor MCP que brinda a los asistentes de IA acceso
al contenido de D&D 5.ª edición de la API Open5e: conjuros,
monstruos, clases, especies, equipo, referencias de reglas, además de
herramientas para construir encuentros y personajes. Utiliza la API v2 de Open5e.
Requisitos
- Node.js 20 o superior (desarrollado con Node 26)
- Acceso de red a
api.open5e.com
Configuración
npm install
npm run build
Conexión de un cliente
El servidor habla JSON-RPC a través de stdio. Apunta tu cliente MCP al punto
de entrada compilado:
{
"mcpServers": {
"dnd-5e": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "/absolute/path/to/dnd-mcp"
}
}
}
Establece cwd en el lugar donde clonaste este repositorio. Un punto
de partida está en mcp.json.
Verifica que responde:
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node dist/index.js
Herramientas
Toda herramienta, excepto get_api_stats, también acepta dos argumentos
opcionales que la restringen a ciertos libros de fuentes:
ruleset: "5e-2014", "5e-2024" o "a5e";sources: claves de documentos de Open5e, p. ej. ["srd-2014", "toh"].
Sin ellos, las búsquedas cubren todas las fuentes que sirve Open5e. Cada
resultado lleva una etiqueta source (clave de documento, título y
conjunto de reglas), y las búsquedas por nombre prefieren el SRD de 2024 y
luego el SRD de 2014. Las construcciones de personajes usan por defecto solo
el SRD de 2024 (ver ADR-008); pasa
ruleset: "5e-2014" o sources: ["srd-2014"] para las reglas antiguas. Un
conjunto de reglas o documento desconocido es un error. Una construcción que
mezcla ediciones, p. ej. sources: ["srd-2024", "open5e"], usa especies y trasfondos de 2014
como permite el Player's Handbook de 2024: la especie conserva sus rasgos y
los aumentos de habilidad provienen del trasfondo. Para añadir trasfondos sin
añadir nada más, pasa background_sources a generate_character_build, p. ej.
background_sources: ["toh"] para los 19 trasfondos de Tome of Heroes.
Búsqueda universal
| Herramienta | Descripción | Obligatoria |
|---|
unified_search | Busca en todos los tipos de contenido de D&D (conjuros, monstruos, objetos, razas, clases, etc.) con clasificación y filtrado inteligentes | query |
Conjuros
| Herramienta | Descripción | Obligatoria |
|---|
search_spells | Busca conjuros por nombre, nivel, escuela o lista de clase | - |
get_spell_details | Obtén información detallada sobre un conjuro específico de D&D 5E | spell_name |
get_spell_by_level | Obtén todos los conjuros de un nivel específico | level |
get_spells_by_class | Obtén los conjuros de la lista de una clase, del nivel más bajo al más alto; filtra por level o max_level | class_name |
Clases y especies
| Herramienta | Descripción | Obligatoria |
|---|
search_classes | Lista las clases base de D&D 5E con sus rasgos y nombres de subclases | - |
get_class_details | Obtén una clase: dado de golpe, competencias, rasgos por nivel, espacios de conjuro y subclases con sus rasgos | class_name |
search_races | Busca especies, incluidas subespecies cuyos nombres omiten la principal (Lightfoot para Halfling) | - |
get_race_details | Obtén una especie con lo que hereda resuelto: tamaño, velocidad, aumentos de habilidad combinados, rasgos parentales | race_name |
Monstruos
| Herramienta | Descripción | Obligatoria |
|---|
search_monsters | Busca monstruos por nombre, índice de desafío, tipo o entorno | - |
get_monsters_by_cr | Obtén monstruos por índice de desafío | challenge_rating |
get_monsters_by_cr_range | Obtén monstruos dentro de un rango de índice de desafío, opcionalmente por entorno y tipo | min_cr, max_cr |
Equipo y objetos
| Herramienta | Descripción | Obligatoria |
|---|
search_weapons | Busca armas de D&D 5E con filtrado por propiedades | - |
search_magic_items | Busca objetos mágicos por nombre, rareza, categoría o sintonía | - |
get_magic_item_details | Obtén información detallada sobre un objeto mágico específico de D&D 5E | item_name |
search_armor | Busca armaduras de D&D 5E con opciones de filtrado | - |
get_armor_details | Obtén información detallada sobre una armadura específica de D&D 5E | armor_name |
Opciones de personaje
| Herramienta | Descripción | Obligatoria |
|---|
search_feats | Busca dotes de D&D 5E con opciones de filtrado | - |
get_feat_details | Obtén información detallada sobre una dote específica de D&D 5E | feat_name |
search_backgrounds | Busca trasfondos de personaje de D&D 5E con opciones de filtrado | - |
get_background_details | Obtén información detallada sobre un trasfondo específico de D&D 5E | background_name |
Referencia de reglas
| Herramienta | Descripción | Obligatoria |
|---|
search_conditions | Busca condiciones y estados de D&D 5E | - |
get_condition_details | Obtén una condición, con su redacción para el conjunto de reglas solicitado | condition_name |
get_all_conditions | Obtén todas las condiciones de D&D 5E para referencia rápida | - |
search_sections | Busca secciones de reglas por nombre o texto | - |
get_section_details | Obtén una sección de reglas por nombre o clave | section_name |
get_all_sections | Lista todas las secciones de reglas por nombre, clave y capítulo, sin el texto | - |
Herramientas de DM
| Herramienta | Descripción | Obligatoria |
|---|
build_encounter | Construye un encuentro equilibrado para un grupo, muestreando monstruos de todo el rango de CR | party_size, party_level, difficulty |
calculate_encounter_difficulty | Calcula la dificultad de un encuentro personalizado con monstruos específicos | party_size, party_level, monsters |
Herramientas de jugador
| Herramienta | Descripción | Obligatoria |
|---|
generate_character_build | Genera una construcción: especie, clase y subclase, trasfondo, puntuaciones de habilidad, puntos de golpe, conjuros, dotes y un plan nivel por nivel | - |
compare_character_builds | Genera y compara múltiples construcciones de personaje con diferentes opciones | build_options |
get_build_recommendations | Obtén recomendaciones de construcción de personaje según la composición del grupo y las necesidades de la campaña | existing_party, campaign_type |
Diagnóstico
| Herramienta | Descripción | Obligatoria |
|---|
get_api_stats | Obtén estadísticas de rendimiento y caché de la API | - |
Desarrollo
npm run dev # watch mode
npm run build # compile to dist/
npm run lint # eslint over src/
npm test # unit tests, no network (builds first)
npm run test:integration # live Open5e API tests
npm run test:all # both suites
Las pruebas usan el ejecutor de pruebas integrado de Node. test/unit/ simula
fetch, por lo que se ejecuta sin conexión y rápido; test/integration/
ejercita la API real y el proceso real del servidor. Ver
docs/testing.md.
Peculiaridades conocidas
- Nombres duplicados entre libros. Una búsqueda de
fireball devuelve
la Fireball de cada libro de fuentes, cada una etiquetada con su source.
Las búsquedas de detalle eligen una (SRD de 2024 primero); pasa
ruleset o sources para elegir otra.
- Filtrado ascendente desigual. Open5e ignora muchos parámetros de filtro y
devuelve la colección completa. El cliente envía solo parámetros verificados y
compara el resto localmente; ver docs/api-filters.md.
- Las lagunas en los datos de Open5e se informan, no se adivinan. Ejemplos:
no hay listas de conjuros del SRD de 2014 para el Paladín, y algunas
herencias de Tome of Heroes no tienen fuente para su tamaño. Busca en el
warnings de una construcción o en el resolved.unresolved de una especie.
- Las construcciones son opinadas. Las reglas del juego (espacios de
conjuro, puntos de golpe, ASI) provienen del SRD, pero las elecciones de
puntuación que eligen una clase, especie o conjuro son criterios subjetivos,
recopilados en
src/character-build/heuristics.ts. No se admiten construcciones multiclase;
allow_multiclass: true se rechaza.
- Conteo de
unified_search frente a objetos. Para classes, el
count informado puede superar el número de objetos devueltos,
porque las clases se listan completas y luego se clasifican frente a la consulta.
Documentación
Fuente de datos y licencia
El contenido proviene de la API de Open5e, que sirve material publicado bajo
las licencias OGL y Creative Commons. Este servidor tiene licencia MIT; el
contenido del juego que devuelve se rige por sus propias licencias. El
source de cada objeto nombra el documento del que proviene.