-
security-
license-
qualityAn MCP server implementation that enables searching and retrieving research articles from PubMed with specific focus on open access content filtering and full-text link retrieval.
Last updated -
8
3
The PubMed MCP Server provides comprehensive tools for searching, retrieving, analyzing, and exporting information from PubMed via the Model Context Protocol (MCP).
Key capabilities include:
Advanced searching using complex criteria (keywords, date ranges, article types) and logical operators (AND, OR, NOT) across specific fields
Retrieving detailed article information including abstracts, metadata, and citation metrics by PMID
Finding related articles for a given PMID
Author-specific searches with co-author information
Journal-specific searches with journal metrics and notable articles
MeSH term exploration for precise medical subject searching
Publication trend analysis over time for research topics
Comparing multiple articles side by side based on various fields
Identifying trending medical topics based on recent publications
Exporting citations in multiple formats (BibTeX, APA, MLA, Chicago, Vancouver, EndNote, RIS)
Customizing results by controlling quantity and sort order
Provides containerization support with built-in Docker integration, enabling easy deployment and consistent runtime environment through provided Dockerfile and docker-compose configurations.
Used for configuration management, allowing users to set up required NCBI API credentials and optional settings like cache parameters and rate limits through environment variables.
Integrates with GitHub for issue tracking, documentation hosting via wiki, and community discussions, providing support channels for users of the MCP server.
Provides advanced PubMed literature search capabilities with complex filters, citation formatting in multiple formats, article details retrieval, author search, related article discovery, MeSH term exploration, journal analysis, and research trend analysis.
Utilized for data validation and modeling within the MCP server, enabling structured handling of PubMed data and tool requests.
Built on Python with specific version requirements (3.8+), leveraging Python's ecosystem for the MCP server implementation.
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
Clone the repository:
git clone https://github.com/your-org/pubmed-mcp.git cd pubmed-mcpInstall dependencies:
pip install -r requirements.txtSet up environment variables:
cp env.example .env # Edit .env with your NCBI API key and emailRun 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
Visit NCBI Account Settings
Sign in or create an account
Navigate to "API Key Management"
Create a new API key
Copy the key to your
.envfile
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 syntaxmax_results: Maximum number of results (1-200)sort_order: Sort order (relevance, pub_date, author, journal, title)date_from/date_to: Date range filtersdate_range: Predefined ranges (1y, 5y, 10y, all)article_types: Filter by publication typesauthors: Filter by author namesjournals: Filter by journal namesmesh_terms: Filter by MeSH termslanguage: Language filter (e.g., 'eng', 'fre')has_abstract: Only articles with abstractshas_full_text: Only articles with full texthumans_only: Only human studies
Citation Formats
bibtex: BibTeX formatapa: APA stylemla: MLA stylechicago: Chicago stylevancouver: Vancouver styleendnote: EndNote formatris: RIS format
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
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.
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that provides access to the DBLP computer science bibliography database, allowing AI models to search publications, process citations, and generate accurate BibTeX entries.Last updated -614MIT License
- Asecurity-licenseAqualityA Model Context Protocol server that enables querying the Crossref API to search for academic publications by title, author, or DOI, returning structured metadata about scholarly works.Last updated -3171MIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that enables natural language interaction with arXiv.org, allowing users to search, retrieve metadata, download PDFs, and load scholarly articles into LLM context.Last updated -532MIT License