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

Related MCP server: PubMed MCP Server

Architecture

graph TB
  A[User] --> B[MCP Server<br/>pubmed_server.py]
  B --> C[search_pubmed function]
  C --> D[Entrez.esearch<br/>Search in PubMed]
  D --> E[PubMed database<br/>NCBI]
  E --> F[List of PMIDs]
  F --> G[Entrez.efetch<br/>Fetch details]
  G --> E
  G --> H[Article XML records]
  H --> I[Data processing]
  I --> J[Extraction of:<br/>- Title<br/>- Authors<br/>- Abstract<br/>- Journal<br/>- Date]
  J --> K[List of articles<br/>in JSON format]
  K --> L[Response to user]

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

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

  subgraph "Configuration"
    O[Entrez.email<br/>Configured in code]
  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_server.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_server.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_server.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_server.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.