PubMed MCP Server

Search and download scientific articles from PubMed's E-utilities API.

View on GitHub →

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.

  1. 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:

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

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:

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

Option 2: Configure in Claude Desktop

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

{
  "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"
      }
    }
  }
}

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

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)

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/

Related Servers