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:

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