PubMed MCP Server

A comprehensive Model Context Protocol (MCP) server for PubMed literature search and management. This server provides advanced search capabilities, citation formatting, and research analysis tools through the MCP protocol.

Features

• Advanced PubMed Search: Search with complex filters including date ranges, article types, authors, journals, and MeSH terms
• Article Details: Retrieve detailed information for specific PMIDs including abstracts, authors, and metadata
• Citation Export: Export citations in multiple formats (BibTeX, APA, MLA, Chicago, Vancouver, EndNote, RIS)
• Author Search: Find articles by specific authors with co-author information
• Related Articles: Discover articles related to a specific PMID
• MeSH Term Search: Search and explore Medical Subject Headings
• Journal Analysis: Get metrics and recent articles from specific journals
• Research Trends: Analyze publication trends over time
• Article Comparison: Compare multiple articles side by side
• Caching: Built-in caching for improved performance
• Rate Limiting: Respectful API usage with configurable rate limits

Installation

Prerequisites

• Python 3.8 or higher
• NCBI API key (free registration required)
• Valid email address for NCBI API identification

Quick Start

1. Clone the repository:

   git clone https://github.com/your-org/pubmed-mcp.git
   cd pubmed-mcp
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Set up environment variables:

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

4. Run the server:

   python -m src.main
   

Development Installation

For development with additional tools:

make install-dev

Or manually:

pip install -r requirements.txt
pip install -e .
pip install black isort mypy flake8

Configuration

Create a .env file in the project root with the following variables:

# Required
PUBMED_API_KEY=your_ncbi_api_key_here
PUBMED_EMAIL=your.email@example.com

# Optional
CACHE_TTL=300
CACHE_MAX_SIZE=1000
RATE_LIMIT=3.0
LOG_LEVEL=info

Getting an NCBI API Key

1. Visit NCBI Account Settings
2. Sign in or create an account
3. Navigate to "API Key Management"
4. Create a new API key
5. Copy the key to your .env file

Usage

Available Tools

The server provides the following MCP tools:

1. search_pubmed

Search PubMed with advanced filtering options.

{
  "query": "machine learning healthcare",
  "max_results": 20,
  "date_range": "5y",
  "article_types": ["Journal Article", "Review"],
  "has_abstract": true
}

2. get_article_details

Get detailed information for specific PMIDs.

{
  "pmids": ["12345678", "87654321"],
  "include_abstracts": true,
  "include_citations": false
}

3. search_by_author

Search for articles by a specific author.

{
  "author_name": "Smith J",
  "max_results": 10,
  "include_coauthors": true
}

4. export_citations

Export citations in various formats.

{
  "pmids": ["12345678"],
  "format": "bibtex",
  "include_abstracts": false
}

5. find_related_articles

Find articles related to a specific PMID.

{
  "pmid": "12345678",
  "max_results": 10
}

6. search_mesh_terms

Search using MeSH terms.

{
  "term": "Machine Learning",
  "max_results": 20
}

7. analyze_research_trends

Analyze publication trends over time.

{
  "topic": "artificial intelligence",
  "years_back": 5,
  "include_subtopics": false
}

Example Usage with MCP Client

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="python",
        args=["-m", "src.main"]
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize the session
            await session.initialize()

            # Search PubMed
            result = await session.call_tool(
                "search_pubmed",
                {
                    "query": "COVID-19 vaccines",
                    "max_results": 5,
                    "date_range": "1y"
                }
            )

            print(result.content[0].text)

if __name__ == "__main__":
    asyncio.run(main())

Development

Running Tests

# Run all tests
make test

# Run with coverage
make test-coverage

# Run specific test types
python run_tests.py unit
python run_tests.py integration
python run_tests.py coverage

Code Quality

# Format code
make format

# Run linting
make lint

# Type checking
mypy src/

Project Structure

pubmed-mcp/
├── src/
│   ├── __init__.py
│   ├── main.py              # Entry point
│   ├── server.py            # MCP server implementation
│   ├── models.py            # Pydantic models
│   ├── pubmed_client.py     # PubMed API client
│   ├── tool_handler.py      # Tool request handlers
│   ├── citation_formatter.py # Citation formatting
│   ├── tools.py             # Tool definitions
│   └── utils.py             # Utility functions
├── tests/                   # Test suite
├── requirements.txt         # Dependencies
├── setup.py                 # Package setup
├── pyproject.toml          # Modern Python config
├── Makefile                # Development commands
├── Dockerfile              # Container setup
└── README.md               # This file

Docker

Build and Run

# Build Docker image
make docker-build

# Run with environment variables
make docker-run PUBMED_API_KEY=your_key PUBMED_EMAIL=your_email

Docker Compose

version: '3.8'
services:
  pubmed-mcp:
    build: .
    environment:
      - PUBMED_API_KEY=your_key
      - PUBMED_EMAIL=your_email
      - LOG_LEVEL=info
    volumes:
      - ./data:/app/data

API Reference

Search Parameters

• query: Search query using PubMed syntax
• max_results: Maximum number of results (1-200)
• sort_order: Sort order (relevance, pub_date, author, journal, title)
• date_from/date_to: Date range filters
• date_range: Predefined ranges (1y, 5y, 10y, all)
• article_types: Filter by publication types
• authors: Filter by author names
• journals: Filter by journal names
• mesh_terms: Filter by MeSH terms
• language: Language filter (e.g., 'eng', 'fre')
• has_abstract: Only articles with abstracts
• has_full_text: Only articles with full text
• humans_only: Only human studies

Citation Formats

• bibtex: BibTeX format
• apa: APA style
• mla: MLA style
• chicago: Chicago style
• vancouver: Vancouver style
• endnote: EndNote format
• ris: RIS format

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

Development Guidelines

• Follow PEP 8 style guidelines
• Add type hints to all functions
• Write comprehensive tests
• Update documentation for new features
• Use conventional commit messages

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: Project Wiki
• Discussions: GitHub Discussions

Acknowledgments

• NCBI E-utilities for PubMed API access
• Model Context Protocol for the MCP specification
• Anthropic for MCP development and support

Changelog

See CHANGELOG.md for a detailed history of changes.

---

Note: This server requires a valid NCBI API key and follows NCBI's usage guidelines. Please be respectful of API rate limits and terms of service.