PubMed-MCP

A Model Context Protocol (MCP) server that provides tools for searching PubMed articles using the NCBI Entrez API.

Author: Emilio Delgado Muñoz

Features

• Search PubMed for articles based on queries
• Retrieve detailed information including title, authors, abstract, journal, and publication date
• Returns results in JSON format
• Configurable maximum number of results

Architecture

graph TB
    A[Usuario] --> B[MCP Server<br/>pubmed_search.py]
    B --> C[Función search_pubmed]
    C --> D[Entrez.esearch<br/>Búsqueda en PubMed]
    D --> E[Base de datos PubMed<br/>NCBI]
    E --> F[Lista de PMIDs]
    F --> G[Entrez.efetch<br/>Obtener detalles]
    G --> E
    G --> H[Registros XML<br/>de artículos]
    H --> I[Procesamiento de datos]
    I --> J[Extracción de:<br/>- Título<br/>- Autores<br/>- Abstract<br/>- Journal<br/>- Fecha]
    J --> K[Lista de artículos<br/>en formato JSON]
    K --> L[Respuesta al usuario]

    subgraph "Dependencias"
        M[BioPython<br/>requirements.txt]
        N[FastMCP<br/>requirements.txt]
    end

    B -.-> M
    B -.-> N

    subgraph "Configuración"
        O[Entrez.email<br/>Configurado en código]
    end

    C -.-> O

    style A fill:#e1f5fe
    style L fill:#c8e6c9
    style E fill:#fff3e0

Installation

1. Clone this repository:

   git clone <repository-url>
   cd PubMed-MCP
   

2. Install dependencies:

   uv sync
   

3. Configure your email in pubmed_search.py:

   Entrez.email = 'your-email@example.com'  # Replace with your actual email
   

VS Code Configuration

To use this MCP server locally in VS Code, the project includes a pre-configured .vscode/mcp.json file. This file tells VS Code how to run the MCP server.

The configuration is already set up to use uv for running the server:

{
  "servers": {
    "pubmed-mcp": {
      "command": "uv",
      "args": ["run", "${workspaceFolder}/pubmed_search.py"]
    }
  }
}

Requirements for VS Code Integration

• VS Code with MCP extension support
• uv package manager installed
• Python virtual environment set up

Alternative Configuration

If you prefer to use pip instead of uv, you can modify the .vscode/mcp.json file:

{
  "servers": {
    "pubmed-mcp": {
      "command": "python",
      "args": ["${workspaceFolder}/pubmed_search.py"]
    }
  }
}

Make sure your virtual environment is activated when using this configuration.

Requirements

• Python 3.11+
• BioPython
• FastMCP

Usage

Run the MCP server:

python pubmed_search.py

The server will start and listen for MCP protocol messages on stdin/stdout.

Available Tools

search_pubmed

Searches PubMed for articles matching the given query.

Parameters:

• query (string): The search query
• max_results (integer, optional): Maximum number of results to return (default: 10)
• title (bool, optional): If true (default) search in Title field
• abstract (bool, optional): If true (default) search in Abstract field
• keywords (bool, optional): If true (default) expand search with Author Keywords ([ot]) and MeSH Headings ([mh])

Field logic:

• title=True and abstract=True -> query applied as (your terms)[tiab]
• Only title=True -> (your terms)[ti]
• Only abstract=True -> (your terms)[ab]
• Both false -> no field tag (all fields)
• keywords=True -> OR-expanded with (your terms)[ot] OR (your terms)[mh]

Example refined queries:

query = "breast cancer metastasis"
title=True, abstract=True, keywords=True -> (breast cancer metastasis)[tiab] OR ((breast cancer metastasis)[ot] OR (breast cancer metastasis)[mh])
title=True, abstract=False, keywords=False -> (breast cancer metastasis)[ti]
title=False, abstract=False, keywords=True -> (breast cancer metastasis) OR ((breast cancer metastasis)[ot] OR (breast cancer metastasis)[mh])

Returns: A list of article objects containing:

• pmid: PubMed ID
• title: Article title
• authors: List of author names
• abstract: Article abstract
• journal: Journal name
• publication_year: Year of publication
• publication_month: Month of publication
• url: PubMed URL

Configuration

Before using the tool, you must set your email address in the Entrez.email variable. This is required by NCBI's Entrez API.

License

This project is open source. Please check the license file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.