What is Pubmed Mcp

pubmed-mcp is a Model Context Protocol (MCP) server designed to facilitate the search and analysis of PubMed medical literature. It offers advanced filtering, citation formatting, and research tools to enhance the user experience in managing medical literature.

Use cases

Use cases for pubmed-mcp include conducting systematic reviews, analyzing publication trends in specific medical fields, comparing research articles, and managing citations for academic writing.

How to use

To use pubmed-mcp, clone the repository from GitHub, install the required dependencies, set up your environment variables with your NCBI API key and email, and then run the server using Python.

Key features

Key features of pubmed-mcp include advanced PubMed search capabilities, detailed article retrieval, citation export in various formats, author search, related articles discovery, MeSH term search, journal analysis, research trend analysis, article comparison, built-in caching, and rate limiting for API usage.

Where to use

pubmed-mcp can be used in academic research, healthcare, and any field that requires access to PubMed literature for analysis, citation, and research purposes.

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
[email protected]

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