PubMed MCP Server v2 (Version 1.1.3)

A comprehensive Model Context Protocol (MCP) server that provides advanced access to the PubMed database for biomedical literature search, retrieval, and analysis. This server transforms natural language queries into optimized PubMed searches using MeSH terms and provides citation analysis capabilities.

🚀 Features

🔧 Tools

• search_pubmed: Search PubMed with pagination, sorting, output modes, and structured filters
• get_full_abstract: Retrieve complete, untruncated abstracts for specific articles by PMID
• get_full_text: Extract full text from PMC with section filtering (Methods, Results, etc.)
• export_ris: Export citations in RIS format for reference management software
• get_citation_counts: Analyze citation metrics and find citing articles
• find_similar_articles: Find articles similar to a given PMID with relevance scores
• batch_process: Process multiple PMIDs with multiple operations efficiently
• count_results: Get search result count without fetching articles (lightweight)
• convert_ids: Convert between PMID, PMCID, and DOI identifiers

📚 Resources

• pubmed://search/{query}: Access search results as structured JSON resource

💡 Prompts

• generate_search_query: Interactive assistant for creating effective PubMed search strategies

📋 Prerequisites

• Node.js v18.x or higher
• npm or yarn package manager

🎯 Usage

Method 1: NPM Package (Recommended)

Benefits: Easy installation, automatic updates, no local build required.

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

Windows: %APPDATA%\\Claude\\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pubmed": {
      "command": "npx",
      "args": ["-y", "pubmed_mcp_server2"]
    }
  }
}

Claude Code Configuration

claude mcp add pubmed -s project -- cmd /c npx pubmed_mcp_server2

Method 2: Local Development

Use case: For development, customization, or when you want to modify the source code.

🛠️ Installation

1. Clone this repository:

git clone https://github.com/YOUR_USERNAME/pubmed_mcp_server2.git
cd pubmed_mcp_server2

2. Install dependencies:

npm install

3. Build the server:

npm run build

Claude Desktop Integration (Local)

Add to your Claude Desktop configuration file:

Windows: %APPDATA%\\Claude\\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pubmed-server": {
      "command": "node",
      "args": ["C:\\path\\to\\pubmed_mcp_server2\\dist\\index.js"],
      "env": {}
    }
  }
}

Replace the path with your actual installation directory.

Example Usage

1. Search with Pagination and Sorting (NEW in v1.1.0)

search_pubmed: {
  query: "COVID-19 vaccine",
  maxResults: 10,
  retstart: 0,           // Start from first result
  sort: "pub_date",      // Sort by Most Recent
  output_mode: "compact" // Minimal output for context savings
}
→ Returns: JSON with total count, compact article list, and next_start for pagination

2. Search with Filters (NEW in v1.1.0)

search_pubmed: {
  query: "diabetes treatment",
  filters: {
    publication_types: ["Clinical Trial", "Meta-Analysis"],
    date_range: { start: "2020", end: "2024" },
    languages: ["eng"],
    humans_only: true,
    free_full_text: true
  }
}

3. Count Results (NEW in v1.1.0)

count_results: { query: "CRISPR gene editing" }
→ Returns: { query, queryTranslation, count: 15234 }
// Lightweight - no article details fetched

4. ID Conversion

convert_ids: { ids: ["33301246"], from_type: "pmid", to_type: "pmcid" }
→ Returns: { conversions: [{ pmid: "33301246", pmcid: "PMC7745181", doi: "10.1056/..." }] }

5. Full Text with Section Filter

get_full_text: {
  pmcIds: ["PMC7745181"],
  sections: ["methods", "results"]  // Only fetch Methods and Results
}
→ Saves 70-90% context compared to full text

6. Citation Analysis

get_citation_counts: "36038128, 30105375"
→ Returns: Citation counts and lists of citing articles for each PMID

7. Find Similar Articles

find_similar_articles: { pmid: "36038128", maxResults: 10 }
→ Returns: Similar articles ranked by NCBI's similarity algorithm with scores

8. Batch Processing

batch_process: {
  pmids: ["36038128", "35105375"],
  operations: ["abstract", "citations", "similar"]
}
→ Returns: Comprehensive analysis of multiple articles in one request

📉 Context Optimization (NEW in v1.1.0)

Output Modes for search_pubmed

| Mode | Use Case | Token Savings | |------|----------|---------------| | compact | Standard searches, batch operations | ~70% | | full | Detailed analysis (default) | 0% |

Note: For count-only queries, use the count_results tool instead.

Section Filtering for get_full_text

| Sections | Typical Size | Use Case | |----------|--------------|----------| | ["all"] | 10,000-50,000 tokens | Complete article review | | ["methods"] | 1,000-3,000 tokens | Methodology analysis | | ["results", "discussion"] | 3,000-8,000 tokens | Findings summary | | ["abstract"] | 200-500 tokens | Quick overview |

🧠 MeSH Term Optimization

The server includes an extensive database of medical term mappings covering:

• COVID-19 & Vaccines: covid, coronavirus, vaccination, immunization
• Cardiovascular: heart attack, myocardial infarction, cardiovascular disease
• Cancer: cancer, tumor, oncology, carcinoma
• Mental Health: depression, anxiety, psychiatric disorders
• Age Groups: elderly, children, pediatric, adolescent
• Study Types: clinical trial, meta-analysis, systematic review, RCT
• Treatment Types: therapy, surgery, medication, drug treatment

🔧 Advanced Search Features

Field Tags Supported

• [ti] - Title
• [ab] - Abstract
• [au] - Author
• [ta] - Journal Title
• [MeSH Terms] - Medical Subject Headings
• [tw] - Text Word
• [pt] - Publication Type
• [pdat] - Publication Date

Boolean Operators

• AND - All terms must be present
• OR - Any of the terms can be present
• NOT - Exclude specific terms
• Parentheses for grouping complex queries

📊 API Endpoints & Rate Limiting

NCBI E-utilities APIs Used

• ESearch: Search and retrieve primary IDs
• EFetch: Retrieve full records and abstracts
• ESummary: Retrieve document summaries
• ELink: Find related articles and citations
• Literature Citation Exporter: RIS format export

Rate Limiting & Limits

• Search results: Maximum 100 articles per query
• Citation analysis: Maximum 20 PMIDs per request
• RIS export: Maximum 50 PMIDs per batch
• Full text: Maximum 10 PMC articles per request
• Similar articles: Maximum 50 similar articles per PMID (default: 10)
• Batch processing: Maximum 50 PMIDs per batch with up to 5 concurrent operations
• API delays: 200-600ms between requests to respect NCBI guidelines

⚙️ Configuration

Customizable Parameters

Edit src/pubmed-api.ts to modify:

// Email for NCBI API (required by NCBI guidelines)
email: '[email protected]'

// Rate limiting delays
const delayBetweenRequests = 200; // milliseconds

// Result limits
const maxResults = 100; // search results
const maxPmids = 20;    // citation analysis

🔍 Error Handling

Comprehensive error handling for:

• Network connectivity issues
• Invalid PMIDs or queries
• API rate limiting and timeouts
• XML/JSON parsing errors
• Missing full text content
• Citation data unavailability

🚧 Development

Available Scripts

npm run build      # Compile TypeScript
npm run dev        # Build and run in development
npm run clean      # Remove compiled files
npm run start      # Start the compiled server

Project Structure

pubmed_mcp_server2/
├── src/
│   ├── index.ts           # Main MCP server setup and tool registration
│   └── pubmed-api.ts      # PubMed API integration and utilities
├── dist/                  # Compiled JavaScript output
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
└── README.md             # This file

Adding New Features

1. New MeSH mappings: Add to MESH_MAPPINGS object in pubmed-api.ts
2. New tools: Register in index.ts using server.registerTool()
3. Field tags: Add to FIELD_TAGS object for query optimization

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and test thoroughly
4. Commit with descriptive messages: git commit -m "Add feature description"
5. Push to your branch: git push origin feature-name
6. Submit a pull request

📖 Documentation

PubMed Search Tips

1. Use MeSH terms for standardized medical vocabulary
2. Combine multiple concepts with AND/OR operators
3. Use field tags to target specific parts of articles
4. Add date ranges to focus on recent research
5. Filter by publication type for specific study designs

Reference Management Integration

The RIS export feature supports:

• Zotero: File → Import
• Mendeley: File → Import → RIS
• EndNote: File → Import → File
• Papers: Import → From File
• RefWorks: Import → References

🛡️ Privacy & Ethics

• No user data is stored or logged
• All queries are sent directly to NCBI APIs
• Complies with NCBI usage guidelines
• Respects API rate limits and terms of service

📄 License

MIT License - see LICENSE file for details

🙋‍♂️ Support

For issues, questions, or contributions:

1. Check existing issues on GitHub
2. Create a new issue with detailed description
3. Include error messages and steps to reproduce

📦 Installation Options

Quick Start (NPM)

npm install -g pubmed_mcp_server2

Update to Latest Version

npm update -g pubmed_mcp_server2

📝 Version History

v1.1.3 (Latest)

• 🔧 Removed: lookup_mesh tool (unstable API)
• 🧹 Cleanup: Streamlined codebase

v1.1.1

• 🔧 Removed: optimize_search_query tool (redundant)
• 🔧 Removed: minimal output mode from search_pubmed (use count_results instead)
• 🧹 Cleanup: Removed unnecessary emojis and decorative separators from output

v1.1.0

• 🆕 Pagination & Sorting: retstart for accessing 101+ results, sort for relevance/pub_date/first_author
• 🆕 Output Modes: compact, full - reduce context consumption by ~70%
• 🆕 Structured Filters: Filter by publication_types, date_range, languages, has_abstract, free_full_text, humans_only
• 🆕 count_results Tool: Lightweight result counting without fetching articles
• 🆕 convert_ids Tool: PMID ⇔ PMCID ⇔ DOI conversion via NCBI ID Converter API
• 🆕 Section Filtering: get_full_text now supports extracting specific sections (methods, results, etc.)

v1.0.2

• 🆕 Batch Processing: Process multiple PMIDs with multiple operations efficiently
• 🔧 Flexible Input: Support for array, space-separated, and comma-separated PMID input
• 📊 Enhanced Analytics: Improved citation analysis and error reporting
• ⚡ Performance: Optimized API rate limiting and concurrent processing

v1.0.1

• 🆕 Similar Articles: Find articles similar to a given PMID using NCBI's algorithm
• 🎯 Improved Relevance: Similarity scores and ranking
• 🔧 Bug Fixes: Enhanced error handling and API stability

v1.0.0

• 🚀 Initial Release: Core PubMed search and analysis functionality
• 📖 Full Features: Search, abstracts, citations, RIS export, query optimization

🔗 Related Resources

• NCBI E-utilities Documentation
• PubMed Search Tips
• MeSH Database
• Model Context Protocol
• Claude Desktop