pubmed-mcp

chrismannina/pubmed-mcp

3.3

If you are the rightful owner of pubmed-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The PubMed MCP Server is a comprehensive tool for advanced literature search and management using the Model Context Protocol.

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 file for details.

Support

Acknowledgments

Changelog

See 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.