README.md•8.68 kB
# PubMed MCP Server
[](https://github.com/chrismannina/pubmed-mcp/actions/workflows/ci.yml)
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.
<a href="https://glama.ai/mcp/servers/@chrismannina/pubmed-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@chrismannina/pubmed-mcp/badge" alt="PubMed Server MCP server" />
</a>
## 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:**
```bash
git clone https://github.com/your-org/pubmed-mcp.git
cd pubmed-mcp
```
2. **Install dependencies:**
```bash
pip install -r requirements.txt
```
3. **Set up environment variables:**
```bash
cp env.example .env
# Edit .env with your NCBI API key and email
```
4. **Run the server:**
```bash
python -m src.main
```
### Development Installation
For development with additional tools:
```bash
make install-dev
```
Or manually:
```bash
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:
```env
# 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](https://www.ncbi.nlm.nih.gov/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.
```json
{
"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.
```json
{
"pmids": ["12345678", "87654321"],
"include_abstracts": true,
"include_citations": false
}
```
#### 3. `search_by_author`
Search for articles by a specific author.
```json
{
"author_name": "Smith J",
"max_results": 10,
"include_coauthors": true
}
```
#### 4. `export_citations`
Export citations in various formats.
```json
{
"pmids": ["12345678"],
"format": "bibtex",
"include_abstracts": false
}
```
#### 5. `find_related_articles`
Find articles related to a specific PMID.
```json
{
"pmid": "12345678",
"max_results": 10
}
```
#### 6. `search_mesh_terms`
Search using MeSH terms.
```json
{
"term": "Machine Learning",
"max_results": 20
}
```
#### 7. `analyze_research_trends`
Analyze publication trends over time.
```json
{
"topic": "artificial intelligence",
"years_back": 5,
"include_subtopics": false
}
```
### Example Usage with MCP Client
```python
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
```bash
# 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
```bash
# 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
```bash
# Build Docker image
make docker-build
# Run with environment variables
make docker-run PUBMED_API_KEY=your_key PUBMED_EMAIL=your_email
```
### Docker Compose
```yaml
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](LICENSE) file for details.
## Support
- **Issues**: [GitHub Issues](https://github.com/your-org/pubmed-mcp/issues)
- **Documentation**: [Project Wiki](https://github.com/your-org/pubmed-mcp/wiki)
- **Discussions**: [GitHub Discussions](https://github.com/your-org/pubmed-mcp/discussions)
## Acknowledgments
- [NCBI E-utilities](https://www.ncbi.nlm.nih.gov/books/NBK25501/) for PubMed API access
- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification
- [Anthropic](https://www.anthropic.com/) for MCP development and support
## Changelog
See [CHANGELOG.md](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.