# PubMed MCP Server

A comprehensive Model Context Protocol (MCP) server that provides access to PubMed, NCBI's database of biomedical literature with over 36 million citations from MEDLINE, life science journals, and online books.

**Developed by [Augmented Nature](https://augmentednature.ai)**

## Overview

The PubMed MCP server exposes the full NCBI E-utilities and PubMed Central APIs through 16 specialized MCP tools, allowing you to search, retrieve, and analyze biomedical literature directly from your MCP-enabled environment.

## Features

### Search & Discovery Tools

- **search_articles** - Search PubMed by keywords, authors, journals, dates, or MeSH terms with pagination
- **advanced_search** - Complex queries with field-specific searches and boolean operators (AND/OR)
- **search_by_author** - Find articles by specific author(s) with optional affiliation filtering
- **search_by_journal** - Search within specific journals with date range filtering
- **search_by_mesh_terms** - Search using Medical Subject Headings (MeSH) with major topic filtering
- **get_trending_articles** - Get recently published articles in a specific field (last 30-365 days)

### Article Retrieval Tools

- **get_article_details** - Get comprehensive metadata and abstract for a specific PMID
- **get_abstract** - Retrieve article abstract by PMID with basic metadata
- **get_full_text** - Retrieve full text from PubMed Central (PMC) when available
- **batch_article_lookup** - Retrieve multiple articles efficiently (up to 200 PMIDs)

### Citation & Reference Tools

- **get_cited_by** - Find articles that cite a specific PMID
- **get_references** - Get reference list for an article
- **get_similar_articles** - Find related articles based on content similarity
- **export_citation** - Export citations in various formats (APA, MLA, Chicago, BibTeX, RIS)

### Utility Tools

- **validate_pmid** - Validate PubMed ID format and check if article exists
- **convert_identifiers** - Convert between PMID, DOI, and PMC ID

### Data Quality Features

- Real-time access to 36+ million biomedical citations
- Automatic rate limiting (3 req/s without API key, 10 req/s with key)
- Comprehensive error handling with retry logic
- Support for all PubMed search fields and operators
- MeSH term integration for precise medical queries
- Full-text access via PubMed Central when available

## Installation

### Prerequisites

- Node.js 16+ (install from [nodejs.org](https://nodejs.org))
- Optional: NCBI API key for higher rate limits (get from [NCBI Account Settings](https://www.ncbi.nlm.nih.gov/account/settings/))

### Basic Configuration (No API Key)

```json
{
  "mcpServers": {
    "pubmed-server": {
      "command": "node",
      "args": ["path/to/pubmed-server/build/index.js"],
      "autoApprove": [
        "search_articles",
        "get_article_details",
        "get_abstract",
        "validate_pmid"
      ]
    }
  }
}
```

### With API Key (Recommended for Higher Rate Limits)

```json
{
  "mcpServers": {
    "pubmed-server": {
      "command": "node",
      "args": ["path/to/pubmed-server/build/index.js"],
      "env": {
        "NCBI_API_KEY": "your_api_key_here",
        "NCBI_EMAIL": "your_email@example.com"
      },
      "autoApprove": [
        "search_articles",
        "get_article_details",
        "get_abstract",
        "validate_pmid",
        "search_by_author",
        "search_by_journal"
      ]
    }
  }
}
```

## Usage Examples

### Search for Recent CRISPR Research

```json
{
  "query": "CRISPR gene editing",
  "max_results": 10,
  "sort": "pub_date"
}
```

### Get Article Details

```json
{
  "pmid": "41138228"
}
```

### Advanced Search with Multiple Criteria

```json
{
  "title": "machine learning",
  "author": "Smith J",
  "mesh_terms": ["Artificial Intelligence", "Diagnosis"],
  "boolean_operator": "AND",
  "max_results": 50
}
```

### Search by Author with Affiliation

```json
{
  "author_name": "Smith J",
  "affiliation": "Harvard Medical School",
  "max_results": 50
}
```

### Search Within Specific Journal

```json
{
  "journal_name": "Nature",
  "keywords": "cancer immunotherapy",
  "date_from": "2024/01/01",
  "date_to": "2025/12/31",
  "max_results": 25
}
```

### Search by MeSH Terms

```json
{
  "mesh_terms": ["COVID-19", "Vaccines"],
  "major_topic_only": true,
  "max_results": 50
}
```

### Get Trending Articles

```json
{
  "field": "artificial intelligence in medicine",
  "days": 30,
  "max_results": 20
}
```

### Get Full Text from PMC

```json
{
  "pmcid": "PMC1234567"
}
```

### Batch Article Lookup

```json
{
  "pmids": ["41138228", "41137959", "41137488"]
}
```

### Export Citation in BibTeX

```json
{
  "pmid": "41138228",
  "format": "bibtex"
}
```

### Find Citing Articles

```json
{
  "pmid": "12345678",
  "max_results": 100
}
```

### Convert Between Identifiers

```json
{
  "identifier": "10.1080/15476286.2025.2577449",
  "identifier_type": "doi"
}
```

## API Reference

### Search Parameters

**Common Parameters:**

- `query` - Search query (keywords, phrases, field tags)
- `max_results` - Number of results (1-1000, default: 20)
- `start` - Starting position for pagination (default: 0)
- `sort` - Sort order: relevance, pub_date, author, journal

**Date Parameters:**

- `date_from` - Start date (YYYY/MM/DD format)
- `date_to` - End date (YYYY/MM/DD format)

**Field Tags:**

- `[Title]` - Article title
- `[Author]` - Author name
- `[Journal]` - Journal name
- `[MeSH Terms]` - Medical Subject Headings
- `[Abstract]` - Abstract text
- `[Affiliation]` - Author affiliation
- `[Publication Type]` - Type of publication
- `[DOI]` - Digital Object Identifier

**Example:** `"Smith J[Author] AND cancer[Title]"`

### MeSH Terms

Medical Subject Headings (MeSH) is the NLM controlled vocabulary thesaurus used for indexing articles. Using MeSH terms provides more precise search results than keyword searches.

**Common MeSH Categories:**

- Diseases
- Chemicals and Drugs
- Analytical, Diagnostic and Therapeutic Techniques
- Anatomy
- Organisms
- Psychiatry and Psychology
- Phenomena and Processes

### Citation Formats

The server supports multiple citation formats:

- **APA** - American Psychological Association
- **MLA** - Modern Language Association
- **Chicago** - Chicago Manual of Style
- **BibTeX** - LaTeX bibliography format
- **RIS** - Research Information Systems format

### Response Format

All tools return structured JSON data including:

- Article metadata (PMID, title, authors, journal, publication date)
- Abstract text (when available)
- MeSH terms and keywords
- DOI and other identifiers
- Citation information
- Full-text availability status

### PMID Format

All PMIDs must be numeric strings (e.g., "12345678")

## Error Handling

The server includes comprehensive error handling for:

- **Network Issues**: Automatic retry with exponential backoff
- **Rate Limiting**: Automatic throttling to comply with NCBI policies
- **Invalid Parameters**: Clear error messages for validation failures
- **API Errors**: Proper HTTP status code handling
- **Missing Data**: Graceful handling of unavailable fields

Common error responses include:

```json
{
  "error": "Invalid PMID format: abc123",
  "isError": true
}
```

## Development

### Building from Source

```bash
# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Development with watch mode
npm run watch
```

### Key Dependencies

- `@modelcontextprotocol/sdk` - MCP server framework
- `axios` - HTTP client for API requests
- `xml2js` - XML parsing for PubMed responses
- TypeScript for type safety and development

## Data Sources

**E-utilities API**: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
**PubMed Central API**: https://www.ncbi.nlm.nih.gov/pmc/tools/developers/
**Coverage**: 36+ million citations from MEDLINE, life science journals, and online books
**Data Updates**: Real-time access to the latest publications

## Rate Limits

- **Without API key**: 3 requests per second
- **With API key**: 10 requests per second

The server automatically handles rate limiting to comply with NCBI's usage policies.

## Troubleshooting

1. **Server Connection Issues**:

   ```bash
   # Test server manually
   cd pubmed-server
   node build/index.js
   # Should show: "PubMed MCP Server running on stdio"
   ```

2. **Invalid PMID Errors**:

   - Ensure PMIDs are numeric strings
   - Example: "12345678" ✓, "PMID12345678" ✗

3. **No Results Returned**:

   - Check search query syntax
   - Try broader search terms
   - Verify field tags are correct

4. **Rate Limit Errors**:

   - Consider obtaining an NCBI API key
   - Reduce request frequency
   - Use batch operations when possible

5. **Full Text Not Available**:
   - Not all articles have full text in PMC
   - Check if article has a PMC ID
   - Some articles may be behind paywalls

## Research Use Cases

- **Literature Review**: Comprehensive search across biomedical literature
- **Citation Analysis**: Track citations and references for research impact
- **Systematic Reviews**: Batch retrieval and analysis of multiple articles
- **Meta-Analysis**: Collect data from multiple studies efficiently
- **Research Trends**: Identify trending topics and recent publications
- **Author Research**: Find all publications by specific researchers
- **Journal Analysis**: Analyze publication patterns in specific journals
- **MeSH-Based Discovery**: Precise medical subject searches

## Compliance & Ethics

This server provides access to publicly available biomedical literature from PubMed. Users should:

- Follow institutional policies for research and publication
- Respect copyright and licensing terms for full-text articles
- Cite sources appropriately in publications
- Use data for legitimate research and educational purposes
- Comply with NCBI's usage policies and rate limits

## License

MIT License - See LICENSE file for details

---

**Data Source**: PubMed/NCBI (https://pubmed.ncbi.nlm.nih.gov)
**API Documentation**: https://www.ncbi.nlm.nih.gov/books/NBK25501/
**Server Version**: 1.0.0