@cyanheads/pubmed-mcp-server

v1.4.5

Published

2 months ago

Production-ready PubMed Model Context Protocol (MCP) server that empowers AI agents and research tools with comprehensive access to PubMed's article database. Enables advanced, automated LLM workflows for searching, retrieving, analyzing, and visualizing

🛠️ Tools Overview

This server provides five powerful tools for accessing and analyzing biomedical literature from PubMed:

`pubmed_search_articles`

Search and discover millions of biomedical articles using free-text queries and advanced filters.

Key Features:

Free-text search across all article fields (title, abstract, author, journal).
Filter by publication date range and specific publication types (e.g., "Review", "Clinical Trial").
Sort results by relevance, publication date, author, or journal name.
Optionally fetch brief summaries for top results in the same call.

Example Use Cases:

"Find recent review articles on CRISPR gene editing."
"Show me all publications by Dr. Anthony Fauci in 2023."
"List the latest articles on neuroinflammation in the journal 'Nature'."

📖 View detailed examples →

`pubmed_fetch_contents`

Retrieve detailed, structured metadata for specific articles using their PubMed IDs (PMIDs).

Key Features:

Fetch single or multiple articles (up to 200 at once).
Use ESearch history (queryKey, WebEnv) for batch retrieval of large sets.
Choose from multiple detail levels:
- abstract_plus: Rich, parsed data including abstract, authors, journal, DOI, and keywords.
- full_xml: The complete, raw PubMedArticle XML structure in JSON format.
- medline_text: The classic MEDLINE plain-text format.
- citation_data: Minimal data required for generating citations.
Include optional data like MeSH terms and grant information.

Example Use Cases:

"Get the full abstract and author list for PMID 31772153."
"Fetch citation data for these three PMIDs: 31535994, 29749963, 33836086."
"Retrieve the MEDLINE record for PMID 12345678."

📖 View detailed examples →

`pubmed_article_connections`

Explore the citation network and generate formatted citations for any article.

Key Features:

Discover related literature by finding:
- pubmed_similar_articles: Articles with similar content.
- pubmed_citedin: Articles that have cited the source article.
- pubmed_references: Articles that the source article references.
Generate citations in multiple standard formats in a single call:
- ris: Research Information Systems format for reference managers.
- bibtex: For use with LaTeX and BibTeX.
- apa_string and mla_string: Plain-text citations in APA and MLA style.

Example Use Cases:

"Find 5 articles that are similar to PMID 30310041."
"Who has cited the paper with PMID 29089531?"
"Get the BibTeX and RIS citation for PMID 33577065."

📖 View detailed examples →

📖 View a second example →

`pubmed_research_agent`

Bootstrap a new research project by generating a formal, structured research plan.

Key Features:

Assembles a comprehensive JSON-based research plan from high-level inputs.
Outlines every phase of research: conception, data collection, analysis, and dissemination.
Includes sections for hypotheses, literature search strategies, experimental design, and data analysis pipelines.
Can optionally embed detailed prompts to guide a research agent in executing the plan.

Example Use Cases:

"Draft a research plan to investigate the role of TREM2 in Alzheimer's disease."
"Outline a project on the effects of intermittent fasting on metabolic health, including a PubMed search strategy."
"Create a formal plan for a comparative multi-omics analysis of gut microbiome data."

📖 View detailed examples →

`pubmed_generate_chart`

Visualize publication trends and data with server-side chart generation.

Key Features:

Create PNG charts from structured data arrays.
Supports a wide range of chart types: bar, line, scatter, pie, doughnut, bubble, radar, and polarArea.
Customize chart title, dimensions, axes, and data series.
Ideal for quickly visualizing search results or publication metadata.

Example Use Cases:

"Plot the number of articles published on 'immunotherapy' per year since 2015."
"Create a bar chart showing the top 10 journals by publication count for 'nanotechnology'."
"Make a scatter plot of articles by citation count vs. publication year."

📖 View detailed examples →

✨ Features

This server is built on the mcp-ts-template and inherits its rich feature set:

Robust Error Handling: A unified McpError system ensures consistent, structured error responses.
Full-Stack Observability: Deep insights with structured logging (Winston) and optional, auto-instrumented OpenTelemetry for traces and metrics.
HTTP/STDIO Transports: Flexible deployment with support for both standard I/O and a high-performance Hono-based HTTP server.
Pluggable Authentication: Secure your HTTP transport with out-of-the-box support for none, jwt, or oauth modes.
Input Validation: All tool inputs are rigorously validated against Zod schemas.
Request Context: AsyncLocalStorage provides end-to-end tracing of operations via unique request IDs.
Edge-Ready: Write code once and run it on your local machine or at the edge.

Plus, specialized features for PubMed:

Official API Integration: Type-safe, comprehensive access to the NCBI E-utilities API (ESearch, EFetch, ELink).
Compliant & Resilient: Built-in rate limiting and retry logic to ensure compliance with NCBI policies.
Optimized Data Handling: Automatic parsing and normalization of complex XML responses into clean, agent-consumable JSON.

🚀 Getting Started

MCP Client Settings

Add the following to your MCP Client configuration file (e.g., cline_mcp_settings.json). This ensures the server is automatically installed and run when needed.

{
  "mcpServers": {
    "pubmed-mcp-server": {
      "command": "npx",
      "args": ["@cyanheads/pubmed-mcp-server"],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "MCP_TRANSPORT_TYPE": "http",
        "MCP_HTTP_PORT": "3017",
        "NCBI_API_KEY": "YOUR_NCBI_API_KEY_HERE"
      }
    }
  }
}

Prerequisites

Node.js (>=20.0.0)
npm (comes with Node.js)
NCBI API Key (Recommended for higher rate limits) - Get one here

Manual Installation

Clone the repository: git clone https://github.com/cyanheads/pubmed-mcp-server.git
Navigate into the directory: cd pubmed-mcp-server
Install dependencies: npm install
Build the project: npm run build

⚙️ Configuration

Configure the server via environment variables. For local development, create a .env file in the project root.

▶️ Running the Server

Start in STDIO mode (default): npm start
Start in HTTP mode: npm run start:http
Run local checks and tests: npm run devcheck (lint, format, type-check) and npm test

📂 Project Structure

🧑‍💻 Agent Development Guide

For strict rules when using this server with an AI agent, refer to the .clinerules/clinerules.md file in this repository. Key principles include:

Logic Throws, Handlers Catch: Never use try/catch in your tool's core logic. Always throw a structured McpError on failure. Handlers are responsible for catching and formatting the final response.
Pass the Context: Always pass the RequestContext object through your call stack for logging and tracing.
Singleton Services: Access external services (like the NcbiService) via their singleton getter (getNcbiService()) within the logic file.

🤝 Contributing

Issues and pull requests are welcome! If you plan to contribute, please run the local checks and tests before submitting your PR.

npm run devcheck
npm test

📜 License

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

🛠️ Tools Overview

pubmed_search_articles

pubmed_fetch_contents

pubmed_article_connections

pubmed_research_agent

pubmed_generate_chart

✨ Features

🚀 Getting Started

MCP Client Settings

Prerequisites

Manual Installation

⚙️ Configuration

▶️ Running the Server

📂 Project Structure

🧑‍💻 Agent Development Guide

🤝 Contributing

📜 License

`pubmed_search_articles`

`pubmed_fetch_contents`

`pubmed_article_connections`

`pubmed_research_agent`

`pubmed_generate_chart`