PubMed MCP Server

Pesquise e baixe artigos científicos da API E-utilities do PubMed.

Documentação

PubMed MCP Server

Um servidor Model Context Protocol (MCP) que fornece acesso à API E-utilities do PubMed para busca e download de artigos científicos. Este servidor permite que aplicações LLM pesquisem a vasta base de dados de literatura biomédica do PubMed e recuperem metadados de artigos, resumos e conteúdo completo.

Recursos

Busca de Artigos: Pesquise na base de dados do PubMed com termos de consulta flexíveis
Download de Artigos: Recupere metadados completos de artigos, resumos e conteúdo disponível
Operações em Lote: Baixe múltiplos artigos em uma única solicitação
Resumos de Artigos: Obtenha resumos de documentos com metadados
Múltiplos Formatos: Suporte para formatos de saída XML, JSON e texto
Limitação de Taxa: Limitação automática de taxa para respeitar os limites da API do PubMed
Tratamento de Erros: Tratamento robusto de erros para falhas de API

Instalação

Configuração Rápida (Recomendado)

Clone ou baixe este repositório
Execute o script de configuração:
```
./setup.sh
```
Isso criará um ambiente virtual, instalará as dependências e fornecerá os próximos passos.

Configuração Manual

Clone ou baixe este repositório

Crie e ative o ambiente virtual:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Instale as dependências:
```
pip install -r requirements.txt
```

Configure o ambiente (opcional, mas recomendado):

cp .env.example .env
# Edit .env file with your NCBI API key and email

Configuração

Variáveis de Ambiente

Crie um arquivo .env com a seguinte configuração opcional:

NCBI_API_KEY: Sua chave de API NCBI (aumenta o limite de taxa de 3 para 10 solicitações/segundo)
NCBI_EMAIL: Seu endereço de e-mail (recomendado pelo NCBI para rastreamento de uso da API)

Obtenha sua chave de API NCBI gratuita em: https://www.ncbi.nlm.nih.gov/account/settings/

Uso

Executando o Servidor

Ative o ambiente virtual (se ainda não estiver ativo):

source venv/bin/activate  # On Windows: venv\Scripts\activate

Execute o servidor:
```
python server.py
```

O servidor iniciará e aguardará conexões MCP via stdio.

Para desativar o ambiente virtual quando terminar:
```
deactivate
```

Ferramentas Disponíveis

1. `search_articles`

Pesquise artigos no PubMed que correspondam a uma consulta.

Parâmetros:

query (string, obrigatório): Consulta de busca (ex.: "vacinas COVID-19", "machine learning AND healthcare")
max_results (int, opcional): Número máximo de resultados a retornar (padrão: 20, máximo: 200)
sort (string, opcional): Ordem de classificação - "relevance", "pub_date" ou "first_author" (padrão: "relevance")

Retornos:

pmids: Lista de IDs do PubMed
total_count: Número total de artigos correspondentes
query_used: A consulta de busca executada
results_returned: Número de resultados retornados
sort_order: Ordem de classificação utilizada

Exemplo:

{
  "query": "CRISPR gene editing",
  "max_results": 10,
  "sort": "pub_date"
}

2. `download_article`

Baixe detalhes do artigo pelo ID do PubMed.

Parâmetros:

pmid (string, obrigatório): ID do PubMed (ex.: "33073741")
format_type (string, opcional): Formato do conteúdo - "abstract", "medline" ou "full" (padrão: "abstract")
return_mode (string, opcional): Formato de retorno - "xml", "text" ou "json" (padrão: "xml")

Retornos:

pmid: O ID do PubMed
content: Conteúdo do artigo no formato solicitado
format_type: Tipo de formato utilizado
return_mode: Modo de retorno utilizado
content_length: Comprimento do conteúdo

3. `download_articles_batch`

Baixe múltiplos artigos em uma única solicitação.

Parâmetros:

pmids (lista, obrigatório): Lista de IDs do PubMed
format_type (string, opcional): Formato do conteúdo (padrão: "abstract")
return_mode (string, opcional): Formato de retorno (padrão: "xml")

Retornos:

pmids: Lista de PMIDs solicitados
content: Conteúdo combinado dos artigos
article_count: Número de artigos solicitados
content_length: Comprimento do conteúdo

4. `get_article_summaries`

Obtenha resumos de documentos para artigos (metadados sem conteúdo completo).

Parâmetros:

pmids (lista, obrigatório): Lista de IDs do PubMed

Retornos:

pmids: Lista de PMIDs solicitados
summaries: Dados de resumo em XML
article_count: Número de artigos solicitados

Exemplos de Consultas de Busca

Buscas Básicas

"COVID-19" - Buscar artigos sobre COVID-19
"machine learning" - Buscar artigos sobre machine learning
"breast cancer" - Buscar artigos sobre câncer de mama

Buscas Avançadas

"COVID-19 AND vaccine" - Artigos sobre vacinas COVID-19
"machine learning AND healthcare" - ML em saúde
"CRISPR[Title]" - CRISPR apenas em títulos de artigos
"Nature[Journal]" - Artigos do periódico Nature
"2023[PDAT]" - Artigos publicados em 2023
"Smith J[Author]" - Artigos do autor "Smith J"

Buscas Específicas por Campo

[Title] - Buscar apenas no título
[Author] - Buscar por autor
[Journal] - Buscar por nome do periódico
[PDAT] - Buscar por data de publicação
[MeSH] - Buscar termos MeSH

Integração com Claude Desktop

Opção 1: Usando arquivo .env (Recomendado)

Se você configurou sua chave de API no arquivo .env durante a instalação:

{
  "mcpServers": {
    "pubmed": {
      "command": "/path/to/pubmed-mcp/venv/bin/python",
      "args": ["/path/to/pubmed-mcp/server.py"]
    }
  }
}

Opção 2: Configurar no Claude Desktop

Alternativamente, você pode especificar a chave de API diretamente na configuração do Claude Desktop:

{
  "mcpServers": {
    "pubmed": {
      "command": "/path/to/pubmed-mcp/venv/bin/python",
      "args": ["/path/to/pubmed-mcp/server.py"],
      "env": {
        "NCBI_API_KEY": "your_api_key_here",
        "NCBI_EMAIL": "your_email@example.com"
      }
    }
  }
}

Recomendação: Use a Opção 1 (arquivo .env) para melhor segurança e gerenciamento mais fácil.

Nota: Certifique-se de usar o caminho completo para o executável Python no ambiente virtual (venv/bin/python) para garantir que as dependências corretas estejam disponíveis.

Limites de Taxa

Sem chave de API: 3 solicitações por segundo
Com chave de API: 10 solicitações por segundo
Limite de tamanho de lote: 50 artigos por solicitação em lote

Tratamento de Erros

O servidor fornece tratamento abrangente de erros:

PMIDs inválidos são automaticamente limpos (caracteres não numéricos removidos)
Consultas vazias retornam erros descritivos
Falhas de API são capturadas e relatadas
A limitação de taxa previne abuso da API

Desenvolvimento

Estrutura do Projeto

pubmed-mcp/
├── server.py              # Main MCP server implementation
├── pubmed_client.py       # PubMed API client wrapper
├── requirements.txt       # Python dependencies
├── setup.sh              # Automated setup script
├── .gitignore            # Git ignore file
├── README.md             # This file
├── .env.example          # Environment variables template
└── venv/                 # Virtual environment (created by setup)

Dependências

mcp[cli] - SDK Python MCP
requests - Cliente HTTP para API do PubMed
python-dotenv - Variáveis de ambiente
typing-extensions - Suporte a dicas de tipo

Licença

Este projeto é open source. Verifique os termos de serviço do PubMed para diretrizes de uso da API.

Suporte

Para problemas com este servidor MCP, verifique:

Sua chave de API e configuração de e-mail
Conectividade de rede com os servidores NCBI
Conformidade com a limitação de taxa
Formatos válidos de PMID

Para documentação da API do PubMed, visite: https://www.ncbi.nlm.nih.gov/books/NBK25500/

PubMed MCP Server

Documentação