PubMed MCP Server

A Model Context Protocol (MCP) server that provides access to PubMed's E-utilities API for searching and downloading scientific articles. This server enables LLM applications to search PubMed's vast database of biomedical literature and retrieve article metadata, abstracts, and full content.

Features

• Article Search: Search PubMed database with flexible query terms

• Article Download: Retrieve full article metadata, abstracts, and available content

• Batch Operations: Download multiple articles in a single request

• Article Summaries: Get document summaries with metadata

• Multiple Formats: Support for XML, JSON, and text output formats

• Rate Limiting: Automatic rate limiting to respect PubMed API limits

• Error Handling: Robust error handling for API failures

Installation

Quick Setup (Recommended)

1. Clone or download this repository

2. Run the setup script:

   ./setup.sh

   This will create a virtual environment, install dependencies, and provide next steps.

Manual Setup

1. Clone or download this repository

2. Create and activate virtual environment:

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

3. Install dependencies:

   pip install -r requirements.txt

4. Configure environment (optional but recommended):

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

Configuration

Environment Variables

Create a .env file with the following optional configuration:

• NCBI_API_KEY: Your NCBI API key (increases rate limit from 3 to 10 requests/second)

• NCBI_EMAIL: Your email address (recommended by NCBI for API usage tracking)

Get your free NCBI API key at: https://www.ncbi.nlm.nih.gov/account/settings/

Usage

Running the Server

1. Activate the virtual environment (if not already active):

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

2. Run the server:

   python server.py

The server will start and listen for MCP connections via stdio.

3. To deactivate the virtual environment when done:

   deactivate

Available Tools

1. search_articles

Search PubMed for articles matching a query.

Parameters:

• query (string, required): Search query (e.g., "COVID-19 vaccines", "machine learning AND healthcare")

• max_results (int, optional): Maximum results to return (default: 20, max: 200)

• sort (string, optional): Sort order - "relevance", "pub_date", or "first_author" (default: "relevance")

Returns:

• pmids: List of PubMed IDs

• total_count: Total number of matching articles

• query_used: The search query executed

• results_returned: Number of results returned

• sort_order: Sort order used

Example:

2. download_article

Download article details by PubMed ID.

Parameters:

• pmid (string, required): PubMed ID (e.g., "33073741")

• format_type (string, optional): Content format - "abstract", "medline", or "full" (default: "abstract")

• return_mode (string, optional): Return format - "xml", "text", or "json" (default: "xml")

Returns:

• pmid: The PubMed ID

• content: Article content in requested format

• format_type: Format type used

• return_mode: Return mode used

• content_length: Length of content

3. download_articles_batch

Download multiple articles in a single request.

Parameters:

• pmids (list, required): List of PubMed IDs

• format_type (string, optional): Content format (default: "abstract")

• return_mode (string, optional): Return format (default: "xml")

Returns:

• pmids: List of requested PMIDs

• content: Combined article content

• article_count: Number of articles requested

• content_length: Length of content

4. get_article_summaries

Get document summaries for articles (metadata without full content).

Parameters:

• pmids (list, required): List of PubMed IDs

Returns:

• pmids: List of requested PMIDs

• summaries: XML summary data

• article_count: Number of articles requested

Search Query Examples

Basic Searches

• "COVID-19" - Search for COVID-19 articles

• "machine learning" - Search for machine learning articles

• "breast cancer" - Search for breast cancer articles

Advanced Searches

• "COVID-19 AND vaccine" - Articles about COVID-19 vaccines

• "machine learning AND healthcare" - ML in healthcare

• "CRISPR[Title]" - CRISPR in article titles only

• "Nature[Journal]" - Articles from Nature journal

• "2023[PDAT]" - Articles published in 2023

• "Smith J[Author]" - Articles by author "Smith J"

Field-Specific Searches

• [Title] - Search in title only

• [Author] - Search by author

• [Journal] - Search by journal name

• [PDAT] - Search by publication date

• [MeSH] - Search MeSH terms

Integration with Claude Desktop

Option 1: Using .env file (Recommended)

If you configured your API key in the .env file during installation:

Option 2: Configure in Claude Desktop

Alternatively, you can specify the API key directly in the Claude Desktop configuration:

Recommendation: Use Option 1 (.env file) for better security and easier management.

Note: Make sure to use the full path to the Python executable in the virtual environment (venv/bin/python) to ensure the correct dependencies are available.

Rate Limits

• Without API key: 3 requests per second

• With API key: 10 requests per second

• Batch size limit: 50 articles per batch request

Error Handling

The server provides comprehensive error handling:

• Invalid PMIDs are automatically cleaned (non-numeric characters removed)

• Empty queries return descriptive errors

• API failures are caught and reported

• Rate limiting prevents API abuse

Development

Project Structure

Dependencies

• mcp[cli] - MCP Python SDK

• requests - HTTP client for PubMed API

• python-dotenv - Environment variables

• typing-extensions - Type hints support

License

This project is open source. Please check PubMed's terms of service for API usage guidelines.

Support

For issues with this MCP server, please check:

1. Your API key and email configuration

2. Network connectivity to NCBI servers

3. Rate limiting compliance

4. Valid PMID formats

For PubMed API documentation, visit: https://www.ncbi.nlm.nih.gov/books/NBK25500/