D&D 5E MCP Server

Acesse conteúdo de Dungeons & Dragons 5ª Edição, incluindo magias, classes e monstros, através da API Open5e.

Documentação

Servidor MCP D&D 5E

Um servidor MCP que dá a assistentes de IA acesso ao conteúdo de D&D 5ª Edição da API Open5e: magias, monstros, classes, espécies, equipamentos, referências de regras, além de auxiliares de construção de encontros e de personagens. Ele usa a API v2 do Open5e.

Requisitos

Node.js 20 ou mais recente (desenvolvido com Node 26)
Acesso à rede para api.open5e.com

Configuração

npm install
npm run build

Conectando um cliente

O servidor fala JSON-RPC via stdio. Aponte seu cliente MCP para o ponto de entrada compilado:

{
  "mcpServers": {
    "dnd-5e": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/dnd-mcp"
    }
  }
}

Defina cwd para onde você clonou este repositório. Um ponto de partida está em mcp.json.

Verifique se ele 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

Ferramentas

Toda ferramenta, exceto get_api_stats, também aceita dois argumentos opcionais que a restringem a alguns livros-fonte:

ruleset: "5e-2014", "5e-2024" ou "a5e";
sources: chaves de documentos do Open5e, ex.: ["srd-2014", "toh"].

Sem eles, as buscas cobrem todas as fontes que o Open5e serve. Cada resultado traz um rótulo source (chave do documento, título e conjunto de regras), e consultas por nome preferem o SRD 2024, depois o SRD 2014. Construções de personagem usam apenas o SRD 2024 por padrão (veja ADR-008); passe ruleset: "5e-2014" ou sources: ["srd-2014"] para as regras antigas. Um conjunto de regras ou documento desconhecido é um erro. Uma construção que mistura edições, ex.: sources: ["srd-2024", "open5e"], usa espécies e antecedentes de 2014 da forma que o Livro do Jogador 2024 permite: a espécie mantém seus traços, e os aumentos de habilidade vêm do antecedente. Para adicionar antecedentes sem adicionar mais nada, passe background_sources para generate_character_build, ex.: background_sources: ["toh"] para os 19 antecedentes do Tome of Heroes.

Busca universal

Ferramenta	Descrição	Obrigatória
`unified_search`	Busca em todos os tipos de conteúdo de D&D (magias, monstros, itens, raças, classes, etc.) com classificação e filtragem inteligentes	`query`

Magias

Ferramenta	Descrição	Obrigatória
`search_spells`	Busca magias por nome, nível, escola ou lista de classe	-
`get_spell_details`	Obtém informações detalhadas sobre uma magia específica de D&D 5E	`spell_name`
`get_spell_by_level`	Obtém todas as magias de um nível específico	`level`
`get_spells_by_class`	Obtém as magias da lista de magias de uma classe, do nível mais baixo para cima; filtre por `level` ou `max_level`	`class_name`

Classes e espécies

Ferramenta	Descrição	Obrigatória
`search_classes`	Lista as classes básicas de D&D 5E com seus recursos e nomes de subclasses	-
`get_class_details`	Obtém uma classe: dado de vida, proficiências, recursos por nível, espaços de magia e subclasses com seus recursos	`class_name`
`search_races`	Busca espécies, incluindo subespécies cujos nomes omitem a espécie-mãe (Lightfoot para Halfling)	-
`get_race_details`	Obtém uma espécie com o que ela herda resolvido: tamanho, deslocamento, aumentos de habilidade combinados, traços da espécie-mãe	`race_name`

Monstros

Ferramenta	Descrição	Obrigatória
`search_monsters`	Busca monstros por nome, nível de desafio, tipo ou ambiente	-
`get_monsters_by_cr`	Obtém monstros por nível de desafio	`challenge_rating`
`get_monsters_by_cr_range`	Obtém monstros dentro de uma faixa de nível de desafio, opcionalmente por ambiente e tipo	`min_cr, max_cr`

Equipamentos e itens

Ferramenta	Descrição	Obrigatória
`search_weapons`	Busca armas de D&D 5E com filtragem por propriedade	-
`search_magic_items`	Busca itens mágicos por nome, raridade, categoria ou sintonia	-
`get_magic_item_details`	Obtém informações detalhadas sobre um item mágico específico de D&D 5E	`item_name`
`search_armor`	Busca armaduras de D&D 5E com opções de filtragem	-
`get_armor_details`	Obtém informações detalhadas sobre uma armadura específica de D&D 5E	`armor_name`

Opções de personagem

Ferramenta	Descrição	Obrigatória
`search_feats`	Busca talentos de D&D 5E com opções de filtragem	-
`get_feat_details`	Obtém informações detalhadas sobre um talento específico de D&D 5E	`feat_name`
`search_backgrounds`	Busca antecedentes de personagem de D&D 5E com opções de filtragem	-
`get_background_details`	Obtém informações detalhadas sobre um antecedente específico de D&D 5E	`background_name`

Referência de regras

Ferramenta	Descrição	Obrigatória
`search_conditions`	Busca condições e efeitos de status de D&D 5E	-
`get_condition_details`	Obtém uma condição, com seu texto para o conjunto de regras solicitado	`condition_name`
`get_all_conditions`	Obtém todas as condições de D&D 5E para referência rápida	-
`search_sections`	Busca seções de regras por nome ou texto	-
`get_section_details`	Obtém uma seção de regras por nome ou chave	`section_name`
`get_all_sections`	Lista todas as seções de regras por nome, chave e capítulo, sem o texto	-

Ferramentas do Mestre

Ferramenta	Descrição	Obrigatória
`build_encounter`	Monta um encontro equilibrado para um grupo, amostrando monstros de toda a faixa de ND	`party_size, party_level, difficulty`
`calculate_encounter_difficulty`	Calcula a dificuldade de um encontro personalizado com monstros específicos	`party_size, party_level, monsters`

Ferramentas do jogador

Ferramenta	Descrição	Obrigatória
`generate_character_build`	Gera uma construção: espécie, classe e subclasse, antecedente, valores de habilidade, pontos de vida, magias, talentos e um plano nível por nível	-
`compare_character_builds`	Gera e compara múltiplas construções de personagem com opções diferentes	`build_options`
`get_build_recommendations`	Obtém recomendações de construção de personagem com base na composição do grupo e nas necessidades da campanha	`existing_party, campaign_type`

Diagnóstico

Ferramenta	Descrição	Obrigatória
`get_api_stats`	Obtém estatísticas de desempenho e cache da API	-

Desenvolvimento

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

Os testes usam o executor de testes integrado do Node. test/unit/ simula fetch, então ele roda offline e rápido; test/integration/ exercita a API real e o processo real do servidor. Veja docs/testing.md.

Peculiaridades conhecidas

Nomes duplicados entre livros. Uma busca por fireball retorna a Bola de Fogo de cada livro-fonte, cada uma rotulada com seu source. Consultas detalhadas escolhem uma (SRD 2024 primeiro); passe ruleset ou sources para escolher outra.
Filtragem upstream irregular. O Open5e ignora muitos parâmetros de filtro e retorna a coleção inteira. O cliente envia apenas parâmetros verificados e faz a correspondência do restante localmente; veja docs/api-filters.md.
Lacunas nos dados do Open5e são relatadas, não adivinhadas. Exemplos: nenhuma lista de magias do SRD 2014 inclui o Paladino, e algumas heranças do Tome of Heroes não têm fonte para seu tamanho. Procure no warnings de uma construção ou no resolved.unresolved de uma espécie.
Construções são opinativas. Regras de jogo (espaços de magia, pontos de vida, ASIs) vêm do SRD, mas as escolhas de pontuação que selecionam uma classe, espécie ou magia são decisões de julgamento, reunidas em src/character-build/heuristics.ts. Construções multiclasse não são suportadas; allow_multiclass: true é rejeitado.
Contagem de unified_search vs. itens. Para classes, o count relatado pode exceder o número de itens retornados, porque as classes são listadas inteiras e depois classificadas contra a consulta.

Documentação

docs/api-filters.md - suporte de filtro do Open5e por endpoint
docs/testing.md - como as suítes são organizadas
docs/adr/ - registros de decisão de arquitetura
docs/history/ - relatórios pontuais substituídos
CLAUDE.md - orientação para Claude Code

Fonte de dados e licença

O conteúdo vem da API Open5e, que serve material publicado sob as licenças OGL e Creative Commons. Este servidor é licenciado sob MIT; o conteúdo de jogo que ele retorna é regido por suas próprias licenças. O source de cada item nomeia o documento de onde ele vem.