pubmed-mcp-server

Literatura biomédica do PubMed

Documentação

@cyanheads/pubmed-mcp-server

Pesquise PubMed/Europe PMC, busque artigos e texto completo (PMC/EPMC/Unpaywall), citações, termos MeSH via MCP. STDIO ou Streamable HTTP.

11 Ferramentas • 1 Recurso • 1 Prompt

Servidor Público Hospedado: https://pubmed.caseyjhand.com/mcp

Visão geral

Literatura biomédica do PubMed, PubMed Central e Europe PMC. Pesquise, obtenha metadados e texto completo, resolva identificadores e citações parciais, formate referências e fundamente consultas no vocabulário MeSH. Funciona como um processo stdio, um servidor Streamable HTTP local ou o endpoint público hospedado acima.

Ferramentas

Ferramenta	Descrição
`pubmed_search_articles`	Pesquise no PubMed com sintaxe de consulta completa, filtros estruturados, intervalos de datas e resumos opcionais
`pubmed_fetch_articles`	Obtenha metadados de artigos por PMID: resumo, autores, periódico, termos MeSH, financiamentos, investigadores de um autor coletivo sob solicitação, avisos de retratação e correção vinculados
`pubmed_fetch_fulltext`	Obtenha texto completo por PMID, PMCID ou DOI, com fallback de PMC para Europe PMC para Unpaywall
`pubmed_europepmc_search`	Pesquise no Europe PMC por preprints, patentes, Agricola e registros de acesso aberto que o PubMed não possui
`pubmed_europepmc_fetch`	Obtenha registros completos do Europe PMC, incluindo o resumo não truncado, como `records: [{ source, epmcId }]`
`pubmed_format_citations`	Formate citações em APA 7ª ed., MLA 9ª ed., BibTeX, RIS ou Vancouver (ICMJE/NLM), com avisos de retratação e correção vinculados
`pubmed_find_related`	Encontre artigos semelhantes, artigos citantes ou referências para um PMID
`pubmed_spell_check`	Corrija uma consulta do PubMed com erros de digitação via NCBI ESpell
`pubmed_lookup_mesh`	Consulte cabeçalhos MeSH com números de árvore, notas de escopo e termos de entrada
`pubmed_lookup_citation`	Resolva referências parciais, até 25 por vez, para PMIDs via ECitMatch
`pubmed_convert_ids`	Converta entre DOI, PMID e PMCID via PMC ID Converter

Recursos

Recurso	Descrição
`pubmed://database/info`	Metadados do banco de dados PubMed via EInfo (lista de campos, contagem de registros, última atualização)

Prompts

Prompt	Descrição
`research_plan`	Gere um plano de pesquisa biomédica estruturado em quatro fases

Referência de capacidades

`pubmed_search_articles` _ferramenta

Sintaxe de consulta completa do PubMed, além de filtros (autor, periódico, MeSH, tipo de publicação, idioma, espécie, resumo, texto completo gratuito) e intervalos de datas de publicação/modificação/Entrez
Até 1.000 resultados por página e deslocamentos de até 9.998, ou maxResults: 0 apenas para a contagem de correspondências; summaryCount adiciona resumos para até 50 resultados
Relata totalCount, o effectiveQuery que o PubMed executou e o appliedFilters
Rejeita valores de filtro em branco, datas impossíveis e intervalos de datas invertidos antes de chamar o PubMed

`pubmed_fetch_articles` _ferramenta

Até 200 PMIDs por chamada; ausências são listadas em unavailablePmids
Resumo, autores, periódico, DOI, tipos de publicação, avisos vinculados de retratação/errata/comentário e links; termos MeSH ativados por padrão, financiamentos via includeGrants e os membros de um autor coletivo (seus InvestigatorList, milhares em alguns ensaios de consórcio) via includeInvestigators
Um artigo retratado, corrigido ou questionado abre com o mesmo bloco de aviso que pubmed_format_citations, diretamente abaixo do título
recordType separa artigos de periódicos de capítulos e livros do Bookshelf; maxResponseCharacters opcional adia o excesso para deferred.ids

`pubmed_fetch_fulltext` _ferramenta

pmcids, pmids e dois em qualquer combinação, até 50 identificadores distintos por chamada: os primeiros 10 são obtidos e o restante é retornado em overLimit para uma chamada de acompanhamento. Cada um é tentado contra PMC, depois Europe PMC e depois Unpaywall (precisa de UNPAYWALL_EMAIL); um artigo mencionado por vários deles é obtido e retornado uma vez, e viaSource nomeia a camada que respondeu
source: "pmc" retorna seções (o corpo e depois material de apoio, como agradecimentos, declarações e apêndices), tabelas e figuras; source: "unpaywall" retorna um corpo de texto HTML ou PDF de melhor esforço
Ausências carregam um reason tipado e triedTiers; sections, maxCharacters, overflowMode e maxResponseCharacters limitam a resposta, e truncation relata o que foi cortado

`pubmed_europepmc_search` _ferramenta

Adiciona preprints (PPR), patentes (PAT) e Agricola (AGR) a MED e PMC; padrão para MED, PMC, PPR
Paginação por cursor via cursorMark / nextCursorMark, até 100 por página; resumos chegam como trechos de 400 caracteres
sort opcional de chaves <field> asc|desc separadas por vírgula; relevance é a ordem padrão, e uma ordenação que o Europe PMC não pode usar falha como europepmc_invalid_input
Não registrado quando EUROPEPMC_ENABLED=false

`pubmed_europepmc_fetch` _ferramenta

Até 25 registros por chamada como records: [{ source, epmcId }], cada par copiado de um resultado de pesquisa, com o resumo completo; ids não resolvidos vão para notFound; maxResponseCharacters opcional adia o excesso para deferred.records
Não registrado quando EUROPEPMC_ENABLED=false

`pubmed_format_citations` _ferramenta

Até 50 PMIDs por chamada, em qualquer combinação de apa, mla, bibtex, ris e vancouver
Registros do Bookshelf citam como livros editados, cada capítulo datado pela sua própria última revisão ou data de contribuição; PMIDs que não podem ser obtidos são relatados como indisponíveis
Retratações, erratas e expressões de preocupação que o NCBI vincula a um artigo retornam como notices e são mostradas antes das citações; Vancouver adiciona uma nota Retraction in: / Erratum in: e APA um parêntese de retratação

`pubmed_find_related` _ferramenta

similar, cited_by ou references, até 50 por página com paginação por deslocamento
Faz fallback para Europe PMC e depois OpenAlex, e nomeia o provedor que respondeu; falha como all_providers_failed se nenhum puder

`pubmed_spell_check` _ferramenta

Retorna original, corrected e hasSuggestion; correções entram no lugar, então tags de campo, operadores, espaçamento e símbolos de genes permanecem como escritos
Execute após uma pesquisa sem resultados ou com poucos resultados e depois tente novamente pubmed_search_articles com corrected

`pubmed_lookup_mesh` _ferramenta

Descritores por nome ou termo de texto livre, com uma correspondência exata de cabeçalho fixada primeiro (o descritor, para um cabeçalho de classe de medicamento); até 50 por página, continuado via nextOffset
Registros carregam seu ID único MeSH (meshId, ex.: D000072657) ao lado do UID Entrez; includeDetails (padrão ativado) adiciona números de árvore, notas de escopo e termos de entrada

`pubmed_lookup_citation` _ferramenta

Até 25 citações parciais por chamada; um periódico ou um ano de quatro dígitos é obrigatório, e volume, primeira página e autor refinam a correspondência
Cada uma é correspondida independentemente e retorna como matched, not_found ou ambiguous, com detalhes de recuperação

`pubmed_convert_ids` _ferramenta

Até 50 ids por chamada, todos de um idType declarado (doi, pmid, pmcid); apenas artigos indexados no PMC são resolvidos
Uma linha de sucesso ou erro por id, em ordem, então um lote parcial nunca falha

`pubmed://database/info` _recurso

Chamada EInfo ao vivo para o banco de dados pubmed, retornada como application/json
count, lastUpdate e fields[], cujos nomes são as tags de pesquisa que pubmed_search_articles aceita

`research_plan` _prompt

Argumentos: title, goal e keywords obrigatórios; organism e includeAgentPrompts opcionais
Retorna um plano de pesquisa em quatro fases; includeAgentPrompts: "true" adiciona um bloco de orientação ao agente sob cada uma das suas nove sub-etapas, duas das quais apontam para ferramentas: a revisão de literatura nomeia pubmed_search_articles e pubmed_lookup_mesh, e a etapa de interpretação nomeia pubmed_search_articles

Recursos

Construído sobre @cyanheads/mcp-ts-core: transportes stdio e Streamable HTTP, autenticação plugável (none / jwt / oauth), armazenamento substituível (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), registro estruturado com rastreamento OpenTelemetry opcional.

Específico do PubMed:

NCBI E-utilities (ESearch, EFetch, ESummary, ELink, ESpell, EInfo, ECitMatch) e o PMC ID Converter, com Europe PMC, OpenAlex e Unpaywall preenchendo as lacunas
Fila de solicitações NCBI compartilhada: inícios de solicitação espaçados, concorrência limitada, um período de resfriamento que segura todos os chamadores após um NCBI 429 e um prazo cobrindo espera na fila e novas tentativas
Análise XML construída para os registros inconsistentes do PubMed: resumos estruturados, campos ausentes, formatos de data variados
Identificadores tolerantes: um PMID com zeros à esquerda resolve como o PMID que ele soletra em toda ferramenta que o aceita; pubmed_fetch_fulltext também corresponde DOIs sem diferenciar maiúsculas de minúsculas e IDs PMC com ou sem o prefixo PMC
Formatadores de citação artesanais (APA, MLA, BibTeX, RIS, Vancouver) sem dependências

Saída amigável ao agente:

Proveniência em cada resposta: rótulos de fonte, campos de licença, avisos de melhor esforço em resultados do Unpaywall e eco da consulta efetiva em pesquisas, para que agentes possam julgar no que confiar
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, para que chamadores ramifiquem com base 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"
    }
  }
}

Auto-hospedado / 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.4.0 ou superior (ou Node.js v24+).
Opcional: uma chave de API NCBI aumenta o limite de taxa de 3 para 10 solicitações por segundo.

Instalação

Clone o repositório:

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

Navegue para o diretório:

cd pubmed-mcp-server

Instale as dependências:

bun install

Configure o ambiente:

cp .env.example .env
# edit .env and set NCBI_API_KEY, NCBI_ADMIN_EMAIL, and UNPAYWALL_EMAIL as needed

Configuração

Variável	Descrição	Padrão
`NCBI_API_KEY`	Chave de API do NCBI; aumenta o limite de taxa de 3 para 10 req/s.	nenhum
`NCBI_ADMIN_EMAIL`	E-mail de contato enviado com as solicitações ao NCBI, conforme recomendado pelo NCBI.	nenhum
`NCBI_REQUEST_DELAY_MS`	Intervalo mínimo entre o início de solicitações ao NCBI, em ms.	`400` (`100` com uma 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 para uma chamada NCBI considerando espera na fila, repetições e backoff, em ms. Uma chamada que não puder começar a tempo é rejeitada imediatamente.	`60000`
`UNPAYWALL_EMAIL`	E-mail de contato para o Unpaywall. Definir isso habilita o nível Unpaywall de `pubmed_fetch_fulltext` para DOIs que não são do PMC.	nenhum
`UNPAYWALL_TIMEOUT_MS`	Tempo limite por solicitação para consultas ao Unpaywall e buscas de conteúdo, em ms.	`20000`
`EUROPEPMC_ENABLED`	Defina `false` para desativar todas as chamadas ao Europe PMC: ambas as ferramentas do Europe PMC ficam não registradas, `pubmed_fetch_fulltext` pula esse nível e `pubmed_find_related` pula esse fallback.	`true`
`EUROPEPMC_EMAIL`	E-mail de contato opcional enviado com as solicitações ao Europe PMC.	nenhum
`EUROPEPMC_REQUEST_DELAY_MS`	Intervalo mínimo entre o início de solicitações ao 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 por solicitação para chamadas ao Europe PMC, em ms.	`20000`
`MCP_TRANSPORT_TYPE`	Transporte: `stdio` ou `http`.	`stdio`
`MCP_HTTP_PORT`	Porta do servidor HTTP.	`3010`
`MCP_SESSION_MODE`	Modo de sessão HTTP: `stateless`, `stateful` ou `auto`.	`stateless`
`MCP_AUTH_MODE`	Autenticação: `none`, `jwt` ou `oauth`.	`none`
`MCP_LOG_LEVEL`	Nível de log (`debug`, `info`, `warning`, `error`, etc.).	`info`
`LOGS_DIR`	Diretório para arquivos de log (somente Node.js).	`<app-root>/logs`
`STORAGE_PROVIDER_TYPE`	Backend de armazenamento: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`.	`in-memory`
`OTEL_ENABLED`	Ativar OpenTelemetry.	`false`

Consulte .env.example para todas as configurações do servidor e as substituições comuns do framework.

Executando o servidor

Desenvolvimento local

Compilar e executar 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

Executar 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 dos E-utilities do NCBI — cliente de API, fila, analisador, formatador.
`src/services/europe-pmc`	Serviço Europe PMC — busca + recuperação JATS de `fullTextXML`. Reutiliza o analisador JATS do NCBI.
`src/services/unpaywall`	Serviço Unpaywall — resolução DOI → localização de acesso aberto e busca de conteúdo (HTML/PDF).
`src/services/openalex`	Serviço OpenAlex — provedor de último recurso para `pubmed_find_related`.
`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 de `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 registro de logs, ctx.state para armazenamento
Registre novas ferramentas e recursos nos arrays createApp() em src/index.ts
Encapsule chamadas de API externas: valide dados brutos → normalize para o tipo de domínio → retorne o esquema de saída; nunca invente campos ausentes

Contribuindo

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

bun run devcheck
bun run test

Licença

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

pubmed-mcp-server

Documentação

@cyanheads/pubmed-mcp-server

Visão geral

Ferramentas

Recursos

Prompts

Referência de capacidades

pubmed_search_articles ferramenta

pubmed_fetch_articles ferramenta

pubmed_fetch_fulltext ferramenta

pubmed_europepmc_search ferramenta

pubmed_europepmc_fetch ferramenta

pubmed_format_citations ferramenta

pubmed_find_related ferramenta

pubmed_spell_check ferramenta

pubmed_lookup_mesh ferramenta

pubmed_lookup_citation ferramenta

pubmed_convert_ids ferramenta

pubmed://database/info recurso

research_plan prompt

Recursos

Começando

Instância Pública Hospedada

Auto-hospedado / Local

Pré-requisitos

Instalação

Configuração

Executando o servidor

Desenvolvimento local

Estrutura do projeto

Guia de desenvolvimento

Contribuindo

Licença

`pubmed_search_articles` _ferramenta

`pubmed_fetch_articles` _ferramenta

`pubmed_fetch_fulltext` _ferramenta

`pubmed_europepmc_search` _ferramenta

`pubmed_europepmc_fetch` _ferramenta

`pubmed_format_citations` _ferramenta

`pubmed_find_related` _ferramenta

`pubmed_spell_check` _ferramenta

`pubmed_lookup_mesh` _ferramenta

`pubmed_lookup_citation` _ferramenta

`pubmed_convert_ids` _ferramenta

`pubmed://database/info` _recurso

`research_plan` _prompt