Pubmed MCP Server

🚀 PubMed MCP Server

Empower your AI agents and research tools with seamless PubMed integration! This MCP (Model Context Protocol) server offers comprehensive access to PubMed's biomedical literature database. It enables LLMs and AI agents to search, retrieve, analyze, and visualize scientific publications through NCBI's E-utilities API, equipped with advanced research workflow capabilities. Built on the cyanheads/mcp-ts-template, it follows a modular architecture with robust error handling, logging, and security features.

🚀 Quick Start

The PubMed MCP Server serves as a bridge, allowing applications (MCP Clients) that understand the Model Context Protocol (MCP) to interact directly and efficiently with PubMed's vast biomedical literature database. With this server, your tools can automate research workflows, gain research insights, integrate PubMed into AI - driven research, and visualize research data.

✨ Features

Core Utilities

• Logging: Structured, configurable logging with sensitive data redaction, supporting file rotation, stdout JSON, and MCP notifications.
• Error Handling: Centralized error processing, standardized error types (McpError), and automatic logging.
• Configuration: Environment variable loading (dotenv) with comprehensive validation.
• Input Validation/Sanitization: Uses zod for schema validation and custom sanitization logic.
• Request Context: Tracks and correlates operations via unique request IDs using AsyncLocalStorage.
• Type Safety: Strong typing enforced by TypeScript and Zod schemas.
• HTTP Transport: High - performance HTTP server using Hono, featuring session management with garbage collection, CORS, and IP - based rate limiting.
• Authentication: Robust authentication layer supporting JWT and OAuth 2.1, with fine - grained scope enforcement.
• Deployment: Multi - stage Dockerfile for creating small, secure production images with native dependency support.

PubMed Integration

• NCBI E - utilities Integration: Comprehensive access to ESearch, EFetch, ELink, and ESummary APIs with automatic XML parsing.
• Advanced Search Capabilities: Complex query construction with date ranges, publication types, author filters, and MeSH term support.
• Full Article Metadata: Retrieve complete publication data including abstracts, authors, affiliations, journal information, DOIs, and citation data.
• Citation Network Analysis: Find related articles, citing articles, and reference lists through ELink integration.
• Research Planning: Generate structured research plans with automated literature search strategies.
• Data Visualization: Create PNG charts from publication metadata (bar, line, scatter, pie, bubble, radar, polarArea).
• Multiple Output Formats: Support for JSON, MEDLINE text, full XML, and formatted citations (RIS, BibTeX, APA, MLA).
• Batch Processing: Efficient handling of multiple PMIDs with pagination support.

📦 Installation

Prerequisites

• Node.js (>=18.0.0)
• npm (comes with Node.js)
• Docker (optional, for containerized deployment)
• NCBI API Key (recommended for higher rate limits) - Get one here

Install via npm (recommended)

npm install @cyanheads/pubmed-mcp-server

Alternatively Install from Source

1. Clone the repository:

git clone https://github.com/cyanheads/pubmed-mcp-server.git
cd pubmed-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build
# or npm run rebuild

💻 Usage Examples

Basic Usage

The server provides a suite of tools for interacting with PubMed. Here are some basic usages of these tools:

• To search for PubMed articles:

# Assume you have the server running and configured
# Example of calling search_pubmed_articles
# The actual implementation may vary depending on your MCP client
# Here is a conceptual example
# Replace 'your_query' with your actual query
your_mcp_client_call search_pubmed_articles queryTerm='your_query'

• To fetch detailed article information:

# Replace 'your_pmid' with the actual PMID
your_mcp_client_call fetch_pubmed_content pmids='your_pmid'

Advanced Usage

• For generating a structured research plan:

# Replace the values with your actual research details
your_mcp_client_call pubmed_research_agent project_title_suggestion='Your project title' primary_research_goal='Your research goal' research_keywords='Your keywords'

• For creating a customizable PNG chart:

# Replace the values with your actual data
your_mcp_client_call generate_pubmed_chart chartType='bar' dataValues='[1,2,3]' xField='x' yField='y'

📚 Documentation

Configuration

Environment Variables

Configure the server using environment variables. These environmental variables are set within your MCP client config/settings (e.g., claude_desktop_config.json for Claude Desktop).

MCP Client Settings

Add the following to your MCP client's configuration file (e.g., cline_mcp_settings.json). This configuration uses npx to run the server, which will automatically install the package if not already present:

{
  "mcpServers": {
    "pubmed-mcp-server": {
      "command": "npx",
      "args": ["@cyanheads/pubmed-mcp-server"],
      "env": {
        "NCBI_API_KEY": "your_ncbi_api_key_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Project Structure

The codebase follows a modular structure within the src/ directory:

src/
├── index.ts              # Entry point: Initializes and starts the server
├── config/               # Configuration loading (env vars, package info)
│   └── index.ts
├── mcp-server/           # Core MCP server logic and capability registration
│   ├── server.ts         # Server setup, capability registration
│   ├── transports/       # Transport handling (stdio, http)
│   ├── resources/        # MCP Resource implementations
│   └── tools/            # MCP Tool implementations (subdirs per tool)
├── services/             # External service integrations
│   └── NCBI/             # NCBI E-utilities API client and parsing
├── types-global/         # Shared TypeScript type definitions
└── utils/                # Common utility functions (logger, error handler, etc.)

For a detailed file tree, run npm run tree or see docs/tree.md.

Tools

The PubMed MCP Server provides a comprehensive suite of tools for biomedical literature research, callable via the Model Context Protocol.

Note: All tools support comprehensive error handling and return structured JSON responses.

Examples

Comprehensive usage examples are available in the directory:

• Search PubMed Articles
• Fetch Article Content
• Article Connections
• Research Planning
• Chart Generation - Generated chart examples (bar, line, scatter, pie, bubble, radar, polarArea) are available in the examples/generate_pubmed_chart/ directory.

Development

# Build the project (compile TS to JS in dist/ and make executable)
npm run build

# Test the server locally using the MCP inspector tool (stdio transport)
npm run inspector

# Test the server locally using the MCP inspector tool (http transport)
npm run inspector:http

# Clean build artifacts
npm run clean

# Generate a file tree representation for documentation
npm run tree

# Clean build artifacts and then rebuild the project
npm run rebuild

# Format code with Prettier
npm run format

# Start the server using stdio (default)
npm start
# Or explicitly:
npm run start:stdio

# Start the server using HTTP transport
npm run start:http

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.