pubmed-mcp-server

---

Ferramentas

11 ferramentas para trabalhar com dados do PubMed, PubMed Central e Europe PMC:

Ferramenta	Descrição
pubmed_search_articles	Pesquise no PubMed com sintaxe de consulta completa, filtros específicos de campo, intervalos de datas, paginação e resumos opcionais breves
pubmed_europepmc_search	Pesquise no Europe PMC por preprints, patentes, Agricola e registros OA exclusivos do EPMC que não aparecem no PubMed. Paginação baseada em cursor.
pubmed_europepmc_fetch	Busque registros completos do Europe PMC — incluindo o resumo não truncado — por source + epmcId, o único identificador que muitos registros de preprint, patente e Agricola possuem
pubmed_fetch_articles	Busque metadados completos de artigos por PMIDs — resumo, autores, periódico, termos MeSH, financiamentos
pubmed_fetch_fulltext	Busque artigos de texto completo por uma cadeia: NCBI PMC EFetch → Europe PMC fullTextXML → Unpaywall. Aceita PMIDs, PMCIDs ou DOIs.
pubmed_format_citations	Gere citações formatadas em APA 7ª ed., MLA 9ª ed., BibTeX, RIS ou Vancouver (ICMJE/NLM)
pubmed_find_related	Encontre artigos semelhantes, artigos citantes ou referências para um PMID específico
pubmed_spell_check	Verifique a ortografia de consultas biomédicas usando o serviço ESpell do NCBI
pubmed_lookup_mesh	Pesquise e explore o vocabulário MeSH — números de árvore, notas de escopo, termos de entrada
pubmed_lookup_citation	Resolva referências bibliográficas parciais para IDs do PubMed via ECitMatch
pubmed_convert_ids	Converta entre DOI, PMID e PMCID usando a API PMC ID Converter

pubmed_search_articles

Pesquise no PubMed com sintaxe completa de consulta do NCBI e filtros.

• Consultas de texto livre com a sintaxe booleana completa e de tags de campo do PubMed
• Filtros específicos de campo: autor, periódico, termos MeSH, idioma, espécie
• Filtros comuns: possui resumo, texto completo gratuito
• Filtragem por intervalo de datas por data de publicação, modificação ou data Entrez
• Filtragem por tipo de publicação (Revisão, Ensaio Clínico, Meta-Análise, etc.)
• Ordenar por relevância, data de publicação, autor ou periódico
• Paginação via deslocamento para percorrer grandes conjuntos de resultados
• Resumos breves opcionais para os N principais resultados via ESummary
• Retorna a consulta original mais a consulta PubMed totalmente aplicada e metadados de filtro normalizados

---

pubmed_fetch_articles

Busque metadados completos de artigos por IDs do PubMed.

• Busca em lote de até 200 artigos de uma vez (alterna automaticamente para POST para lotes >= 100)
• Retorna dados estruturados: título, resumo, autores com afiliações deduplicadas, informações do periódico, DOI
• Links diretos para PubMed e PubMed Central (quando disponível)
• Termos MeSH opcionais, informações de financiamento e tipos de publicação
• Lida com o XML inconsistente do PubMed (resumos estruturados, campos ausentes, formatos de data variados)

---

pubmed_fetch_fulltext

Busque artigos de texto completo por uma cadeia de três estágios: NCBI PMC EFetch → Europe PMC fullTextXML → Unpaywall.

• Aceita exatamente um de pmcids (IDs PMC diretos), pmids (IDs do PubMed, resolvidos automaticamente) ou dois (resolvidos automaticamente para PMC via ID Converter; preprints e OA exclusivo do EPMC passam para Europe PMC / Unpaywall)
• NCBI PMC e Europe PMC retornam JATS estruturado; os registros de saída indicam a origem via viaSource: "pmc" | "europepmc" | "unpaywall"
• A camada Europe PMC (habilitada por padrão; desative com EUROPEPMC_ENABLED=false) recupera registros correspondentes ao PMC que o NCBI PMC EFetch não encontrou, e resolve entrada DOI para correspondentes PMC quando existem. O fullTextXML do EPMC é baseado em PMC, então preprints (PPR), patentes (PAT) e Agricola (AGR) são acessíveis via pubmed_europepmc_search para metadados, mas não têm texto completo por esta cadeia.
• A camada Unpaywall (habilitada definindo UNPAYWALL_EMAIL) resolve DOIs para cópias OA legais; extrai páginas de destino HTML para Markdown via Defuddle ou PDFs para texto via unpdf
• Contrato de saída discriminado — source: "pmc" (seções estruturadas, independentemente de ter vindo do PMC ou EPMC) ou source: "unpaywall" (corpo de melhor esforço + contentFormat: html-markdown ou pdf-text)
• Razões estruturadas de indisponibilidade (not-found, no-pmc-fallback-disabled, no-epmc-fulltext, no-doi, no-oa, fetch-failed, parse-failed, service-error) para que chamadores possam tentar novamente ou explicar aos usuários sem analisar texto
• Cada entrada unavailable carrega idType (pmid / pmcid / doi) e triedTiers — resultados por nível (not-attempted, miss, no-fulltext, service-error, …) em ordem de execução, para que chamadores possam ver qual estágio falhou e por quê
• Filtragem de seções por título (correspondência sem diferenciar maiúsculas/minúsculas, ex.: ["methods", "results"]) e máximo de seções configurável aplicam-se à saída do PMC
• Orçamentos de caracteres mantêm o tamanho do contexto previsível: maxCharacters limita o texto do corpo por artigo (seções e subseções do PMC, ou o corpo do Unpaywall), maxCharactersPerSection limita uma única seção do PMC, e overflowMode escolhe entre truncate (preencher seções em ordem de documento) e outline (dividir o orçamento uniformemente para que cada título sobreviva com um trecho). Os orçamentos são executados após os filtros semânticos, e um objeto truncation relata contagens de caracteres por artigo e por seção sempre que algo foi encurtado
• Até 10 artigos por solicitação

---

pubmed_europepmc_search

Pesquise no Europe PMC (EBI/EMBL-EBI), um corpus biomédico de acesso aberto mais amplo que apenas o PubMed.

• Superfícies de registros que a pesquisa do PubMed não alcança — preprints (source: PPR), patentes (source: PAT), Agricola (source: AGR), além de tudo no PubMed (MED) e PMC (PMC). Em consultas recentes, isso pode significar dezenas de resultados relevantes com zero sobreposição com o PubMed.
• Fontes padrão ["MED", "PMC", "PPR"]; passe sources para incluir PAT / AGR
• Paginação baseada em cursor via cursorMark (diferente de pubmed_search_articles, que usa deslocamento) — * para a primeira página, retorne nextCursorMark para a próxima
• Discriminador de saída em source mais pmid / pmcId / doi opcionais para cruzamento
• abstractSnippet é limitado a 400 caracteres para manter uma página limitada; abstractTruncated indica se foi cortado, e pubmed_europepmc_fetch retorna o resumo completo para os registros que valem a pena ler integralmente
• Desabilitado quando EUROPEPMC_ENABLED=false; a ferramenta não é registrada nesse caso

---

pubmed_europepmc_fetch

Busque registros completos do Europe PMC por source + epmcId, a contraparte de detalhes de pubmed_europepmc_search.

• Retorna o resumo completo, não truncado, como texto simples pronto para exibição — marcação removida, entidades HTML decodificadas
• Endereçado pelo source e epmcId de um resultado de pesquisa, o único identificador que registros de preprint (PPR), patente (PAT) e Agricola (AGR) carregam de forma confiável — pubmed_fetch_articles precisa de um PMID e pubmed_fetch_fulltext precisa de um PMCID, PMID ou DOI
• Até 25 registros por chamada, resolvidos em uma única solicitação do Europe PMC
• Retorna solicitações não resolvidas ao chamador em notFound em vez de falhar o lote
• Desabilitado quando EUROPEPMC_ENABLED=false; a ferramenta não é registrada nesse caso

---

pubmed_format_citations

Gere citações formatadas para artigos.

• Cinco estilos de citação: APA 7ª ed., MLA 9ª ed., BibTeX, RIS, Vancouver (ICMJE/NLM)
• Solicite vários estilos por artigo em uma única chamada
• Formatadores artesanais — zero dependências externas, totalmente compatível com Workers
• Até 50 artigos por solicitação
• Relata contagens formatadas e PMIDs indisponíveis para tratamento de resultados parciais

---

pubmed_find_related

Encontre artigos relacionados a um artigo de origem via ELink.

• Três tipos de relacionamento: similar (similaridade de conteúdo), cited_by, references
• Resultados enriquecidos com título, autores, data de publicação e fonte via ESummary
• Resultados retornados na ordem de relevância do NCBI

---

pubmed_spell_check

Verifique a ortografia de uma consulta biomédica usando o ESpell do NCBI.

• Retorna a consulta original, a consulta corrigida e se uma sugestão foi encontrada
• Útil para refinamento de consulta antes de pesquisar

---

pubmed_lookup_mesh

Pesquise e explore o vocabulário MeSH (Medical Subject Headings).

• Pesquise termos MeSH por nome com correspondência exata de cabeçalho
• Registros detalhados com números de árvore, notas de escopo e termos de entrada por padrão
• Útil para construir consultas PubMed precisas com vocabulário controlado

---

pubmed_lookup_citation

Resolva referências bibliográficas parciais para IDs do PubMed via NCBI ECitMatch.

• Corresponda citações por periódico, ano, volume, primeira página e/ou nome do autor
• Mais campos = melhor precisão de correspondência; pelo menos um campo é obrigatório
• Lote de até 25 citações por solicitação
• Correspondência determinística — mais confiável que pesquisa de texto livre para referências conhecidas
• Retorna status explícitos matched, not_found e ambiguous com detalhes de recuperação

---

pubmed_convert_ids

Converta entre identificadores de artigo (DOI, PMID, PMCID) usando a API PMC ID Converter.

• Lote de até 50 IDs por solicitação
• Aceita DOIs, PMIDs ou PMCIDs (todos os IDs devem ser do mesmo tipo)
• Apenas resolve artigos indexados no PubMed Central
• Relatório de sucesso/erro por ID — lotes parciais retornam mapeamentos resolvidos junto com erros estruturados para IDs não resolvíveis, não uma falha no nível do lote

Recurso e prompt

Tipo	Nome	Descrição
Recurso	pubmed://database/info	Metadados do banco de dados PubMed via EInfo (lista de campos, contagem de registros, última atualização)
Prompt	research_plan	Gere um esboço estruturado de plano de pesquisa biomédica em 4 fases

Recursos

Construído sobre @cyanheads/mcp-ts-core:

• Definições declarativas de ferramentas — um arquivo por ferramenta, o framework lida com registro e validação
• Tratamento unificado de erros em todas as ferramentas
• Autenticação plugável (none, jwt, oauth)
• Backends de armazenamento intercambiáveis: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Registro estruturado com rastreamento OpenTelemetry opcional
• Executa localmente (stdio/HTTP) ou em Cloudflare Workers a partir do mesmo código

Específico do PubMed:

• Integração completa com E-utilities do NCBI (ESearch, EFetch, ESummary, ELink, ESpell, EInfo, ECitMatch) mais PMC ID Converter
• Fila de solicitações sequenciais com atraso configurável para conformidade com limite de taxa do NCBI
• Analisador XML específico do NCBI com dicas isArray para a estrutura XML inconsistente do PubMed
• Formatadores de citação artesanais (APA, MLA, BibTeX, RIS, Vancouver) — zero dependências, compatível com Workers

Saída amigável para agentes:

• Proveniência em cada resposta — rótulos de fonte, campos de licença, avisos de melhor esforço em resultados Unpaywall e eco de consulta efetiva em pesquisas para que agentes possam raciocinar sobre confiança
• Falha parcial graciosa — ferramentas em lote retornam linhas de sucesso/erro por item em vez de falhar a solicitação, com códigos de status estruturados e texto acionável de próximos passos
• Contratos de saída discriminados — source: "pmc" | "unpaywall", razões unavailable tipadas, campos viaSource e triedTiers — chamadores ramificam em dados, não em análise de strings

Começando

Instância Pública Hospedada

Uma instância pública está disponível em https://pubmed.caseyjhand.com/mcp — sem necessidade de instalação. Aponte qualquer cliente MCP para ela via Streamable HTTP:

{
  "mcpServers": {
    "pubmed-mcp-server": {
      "type": "streamable-http",
      "url": "https://pubmed.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Adicione o seguinte ao arquivo de configuração do seu cliente MCP.

{
  "mcpServers": {
    "pubmed-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/pubmed-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NCBI_API_KEY": "your-key-here"
      }
    }
  }
}

Ou com npx (sem necessidade de Bun):

{
  "mcpServers": {
    "pubmed-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/pubmed-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NCBI_API_KEY": "your-key-here"
      }
    }
  }
}

Ou com Docker:

{
  "mcpServers": {
    "pubmed-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/pubmed-mcp-server:latest"]
    }
  }
}

Para Streamable HTTP, defina o transporte e inicie o servidor:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Pré-requisitos

• Bun v1.3.2 ou superior.
• Opcional: Chave de API NCBI para limites de taxa mais altos (10 req/s vs 3 req/s).

Instalação

1. Clone o repositório:

git clone https://github.com/cyanheads/pubmed-mcp-server.git

2. Navegue até o diretório:

cd pubmed-mcp-server

3. Instale as dependências:

bun install

Configuração

Toda a configuração é validada na inicialização por meio de esquemas Zod em src/config/server-config.ts. Principais variáveis de ambiente:

Variável	Descrição	Padrão
MCP_TRANSPORT_TYPE	Transporte: stdio ou http	stdio
MCP_HTTP_PORT	Porta do servidor HTTP	3010
MCP_HTTP_ENDPOINT_PATH	Caminho do endpoint HTTP onde o servidor MCP está montado	/mcp
MCP_PUBLIC_URL	Substituição de origem pública para implantações com proxy reverso de terminação TLS (página inicial, Server Card, metadados RFC 9728).	nenhum
MCP_AUTH_MODE	Autenticação: none, jwt ou oauth	none
MCP_LOG_LEVEL	Nível de log (debug, info, warning, error, etc.)	info
MCP_GC_PRESSURE_INTERVAL_MS	Loop de pressão de GC forçado exclusivo do Bun (ms). Drena o ciclo McpServer/McpSessionTransport por solicitação sob tráfego HTTP baixo e sustentado. Ponto de partida recomendado se houver crescimento de heap: 60000.	0 (desativado)
LOGS_DIR	Diretório para arquivos de log (somente Node.js).	<project-root>/logs
STORAGE_PROVIDER_TYPE	Backend de armazenamento: in-memory, filesystem, supabase, cloudflare-kv/r2/d1	in-memory
NCBI_API_KEY	Chave de API NCBI para limites de taxa mais altos (10 req/s vs 3 req/s)	nenhum
NCBI_ADMIN_EMAIL	E-mail de contato enviado com solicitações NCBI (recomendado pela NCBI)	nenhum
NCBI_REQUEST_DELAY_MS	Intervalo mínimo entre o início de solicitações NCBI em ms	334 (100 com chave)
NCBI_MAX_CONCURRENT	Máximo de solicitações NCBI simultâneas em andamento	8
NCBI_MAX_RETRIES	Tentativas de repetição para solicitações NCBI com falha	6
NCBI_TIMEOUT_MS	Tempo limite de HTTP por solicitação em ms	30000
NCBI_TOTAL_DEADLINE_MS	Prazo total em todas as tentativas de repetição para uma chamada NCBI, em ms	60000
UNPAYWALL_EMAIL	E-mail de contato para Unpaywall. Quando definido, pubmed_fetch_fulltext recorre a cópias de acesso aberto do Unpaywall para DOIs não-PMC	nenhum
UNPAYWALL_TIMEOUT_MS	Tempo limite de HTTP por solicitação para consultas e buscas de conteúdo do Unpaywall, em ms	20000
EUROPEPMC_ENABLED	Ativa a ferramenta de busca Europe PMC e a cadeia de fallback pubmed_fetch_fulltext JATS. Defina false para desativar todas as chamadas EPMC e pular o registro da ferramenta.	true
EUROPEPMC_EMAIL	E-mail de contato opcional enviado com solicitações Europe PMC (cortesia da EBI).	nenhum
EUROPEPMC_REQUEST_DELAY_MS	Intervalo mínimo entre o início de solicitações Europe PMC em ms	200
EUROPEPMC_MAX_RETRIES	Tentativas de repetição para solicitações Europe PMC com falha	3
EUROPEPMC_TIMEOUT_MS	Tempo limite de HTTP por solicitação para chamadas Europe PMC, em ms	20000
OTEL_ENABLED	Ativa OpenTelemetry	false

Executando o servidor

Desenvolvimento local

• Compile e execute a versão de produção:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• Execute verificações e testes:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Estrutura do projeto

Diretório	Finalidade
src/mcp-server/tools	Definições de ferramentas (*.tool.ts). Onze ferramentas em PubMed, PMC e Europe PMC.
src/mcp-server/resources	Definições de recursos. Recurso de informações do banco de dados.
src/mcp-server/prompts	Definições de prompts. Prompt de plano de pesquisa.
src/services/ncbi	Camada de serviço NCBI E-utilities — cliente de API, fila, analisador, formatador.
src/services/europe-pmc	Serviço Europe PMC — busca + recuperação JATS fullTextXML. Reutiliza o analisador JATS da NCBI.
src/services/unpaywall	Serviço Unpaywall — resolução de DOI → localização OA e busca de conteúdo (HTML/PDF).
src/config	Análise e validação de variáveis de ambiente específicas do servidor com Zod.
tests/	Testes unitários e de integração, espelhando a estrutura src/.

Guia de desenvolvimento

Consulte CLAUDE.md para diretrizes de desenvolvimento e regras arquiteturais. A versão resumida:

• Handlers lançam exceções, o framework captura — sem try/catch na lógica das ferramentas
• Use ctx.log para logging, ctx.state para armazenamento
• Registre novas ferramentas e recursos nos arrays createApp()

Contribuindo

Issues e pull requests são bem-vindos. Execute verificações e testes antes de enviar:

bun run devcheck
bun run test

Licença

Este projeto está licenciado sob a Licença Apache 2.0. Consulte o arquivo LICENSE para obter detalhes.