Generated by /repo-architecture skill v2.0.0

PubMed MCP Architecture

PubMed MCP is a Model Context Protocol server that provides AI agents with programmatic access to the NCBI PubMed and PubMed Central (PMC) databases. It enables searching, retrieving metadata, accessing full-text articles, finding related papers, converting article identifiers, looking up citations, and checking copyright status across the entire corpus of biomedical and life sciences literature (over 36 million citations).

The server wraps the @cyanheads/pubmed-mcp-server npm package and exposes 7 MCP tools via Server-Sent Events (SSE) transport, bridged from stdio by supergateway. It runs as a Docker container on the hosting_web network, routed through Traefik at pubmed-mcp.home.

Scope: Biomedical and life sciences only — medicine, biology, genetics, pharmacology, neuroscience, and related fields. For physics, CS/AI, or engineering papers, use arXiv or IEEE Xplore instead.
MCP Tools
7
Transport
SSE
Port
3017
Runtime
Node 20
External API
NCBI E-utils
Status
Deployed

2. Runtime Architecture

Diagram A — Runtime Request Flow

SSE / HTTP :3017 stdio HTTPS MCP Client Claude Code / Gemini CLI / MCP Proxy AI agent requesting biomedical literature Traefik Reverse Proxy / TLS pubmed-mcp.home routing supergateway Node.js / SSE bridge stdio-to-HTTP transport pubmed-mcp-server @cyanheads / Node.js / MCP SDK 7 tools for PubMed & PMC access NCBI E-utilities API eutils.ncbi.nlm.nih.gov Legend Primary path External Service Bridge Infra

Request Flow

  1. An MCP client (Claude Code, Gemini CLI, or MCP Proxy) sends a tool call via SSE to pubmed-mcp.home.
  2. Traefik terminates TLS and routes the request to the pubmed-mcp container on port 3017.
  3. supergateway receives the HTTP/SSE request and translates it into stdio messages for the MCP server process.
  4. pubmed-mcp-server parses the MCP tool call, constructs the appropriate NCBI E-utilities API request, and sends it over HTTPS.
  5. The NCBI API returns XML/JSON results which the server transforms into structured MCP tool responses.
  6. The response flows back through supergateway as SSE events to the MCP client.

5. Public Interfaces (MCP Tools)

All tools are exposed via the MCP protocol over SSE transport at pubmed-mcp.home/sse.

Tool Parameters Description
search_articles query (required), max_results, sort, date_from, date_to, datetype, retstart Search PubMed for biomedical articles using keywords, field tags, boolean operators, and date filters. Supports pagination and sorting by relevance, date, author, journal, or title.
get_article_metadata pmids (required, array of strings) Retrieve detailed metadata (title, authors, abstract, journal, DOI, MeSH terms) for one or more PubMed IDs. Attribution and DOI citation required on every use.
find_related_articles pmids (required), link_type, max_results Find related content for given PMIDs. Link types: similar papers (pubmed_pubmed), full-text in PMC (pubmed_pmc), genes, proteins, or nucleotides.
lookup_article_by_citation citations (required, array of objects with journal, year, author, volume, first_page, key) Match bibliography citations to PubMed IDs. Provide 2-3 fields per citation for best results.
convert_article_ids ids (required, array), id_type (pmid, pmcid, or doi) Convert between PMID, PMCID, and DOI formats. Essential for checking PMC full-text availability.
get_full_text_article pmc_ids (required, array of PMC IDs) Retrieve full-text articles from PubMed Central. Only ~6M articles have full text. Requires PMC ID (use convert_article_ids to get it from PMID).
get_copyright_status pmids (required, array) Check copyright and licensing information for articles. Identifies open access, CC BY, and other license types.

Common Workflows

Search and read full text: search_articles → convert_article_ids (PMID to PMCID) → get_full_text_article
Citation matching: lookup_article_by_citation → get_article_metadata
Literature exploration: search_articles → find_related_articles → get_article_metadata

6. Repository Structure

The PubMed MCP server is a minimal Docker wrapper around the @cyanheads/pubmed-mcp-server npm package. No custom application code is maintained in this directory — all logic comes from the upstream package. 

_mcp-tools/
  pubmed-mcp/
    Dockerfile           # Build: node:20-bookworm-slim + npm packages
  docker-compose.yml     # Stack definition (4 MCP services)
  .env                   # NCBI_API_KEY, GRAFANA_TOKEN, HF_TOKEN
  README.md              # Stack documentation
File Classification Purpose
Dockerfile Primary Builds the container image: installs @cyanheads/pubmed-mcp-server and supergateway globally, sets up native dependencies for canvas rendering.
docker-compose.yml Primary Defines the pubmed-mcp service with environment variables, network attachment, and restart policy. Shared with 3 other MCP services.
.env Configuration Contains NCBI_API_KEY for higher NCBI rate limits (10 req/s vs 3 req/s without key).

7. Deployment & Operations

Container Details

PropertyValue
Container namepubmed-mcp
Base imagenode:20-bookworm-slim
Exposed port3017 (internal only, no host binding)
Networkhosting_web (external, shared with Traefik)
Restart policyunless-stopped
Entrypointsupergateway --stdio pubmed-mcp-server --port 3017
DNSpubmed-mcp.home (Pi-hole, LAN only)
TLSTraefik-terminated (local CA wildcard cert)

Build & Deploy

cd /home/rod/_rod/_mcp-tools

# Build and start
docker compose build pubmed-mcp --no-cache
docker compose up -d pubmed-mcp

# Verify
docker logs -f pubmed-mcp
curl -s http://pubmed-mcp.home/sse

Environment Variables

VariableRequiredDescription
NCBI_API_KEY Optional NCBI API key for elevated rate limits (10 req/s). Without it, rate-limited to 3 req/s. Obtain from NCBI account settings.

Health Check

# SSE endpoint — should return event stream headers
curl -s http://pubmed-mcp.home/sse

# Container status
docker inspect pubmed-mcp --format='{{.State.Status}}'

Part of MCP Tools Stack

This service is deployed alongside three other MCP servers in the same docker-compose.yml: grafana-mcp (:8100), huggingface-mcp (:3000), and mermaid-mcp (:3033). All four share the hosting_web network and follow the same deployment pattern.

8. Dependencies

Runtime Dependencies

DependencyTypePurpose
@cyanheads/pubmed-mcp-server npm (global) Core MCP server implementing all 7 PubMed tools via the MCP SDK. Communicates with NCBI E-utilities over HTTPS.
supergateway npm (global) Transport bridge: converts stdio-based MCP server into an HTTP/SSE server on port 3017.
node:20-bookworm-slim Docker base image Node.js 20 LTS runtime on Debian Bookworm (slim variant).

Build-time Dependencies (purged after install)

PackagePurpose
python3Required by node-gyp for native module compilation
build-essentialGCC/make toolchain for native addons
pkg-configLibrary discovery for native dependencies
libcairo2-devCairo graphics library (canvas rendering)
libpango1.0-devPango text layout (canvas text rendering)
libjpeg-devJPEG codec for canvas image output
libgif-devGIF codec for canvas image output
librsvg2-devSVG rendering for canvas

Infrastructure Dependencies

ServiceDependency TypeNotes
Traefik Routing / TLS Routes pubmed-mcp.home to container port 3017. Provides TLS termination via local CA wildcard cert.
Pi-hole DNS Resolves pubmed-mcp.home to 10.0.1.6 for LAN clients.
hosting_web network Docker network External Docker network shared with Traefik and other hosting services.
NCBI E-utilities External API All data comes from eutils.ncbi.nlm.nih.gov. Requires outbound HTTPS. Rate-limited to 3 req/s (or 10 req/s with API key).

9. Constraints & Risks

ConstraintSeverityDetails
NCBI rate limiting Medium Without NCBI_API_KEY, limited to 3 requests/second. With key, 10 req/s. Burst queries may be throttled or blocked by NCBI.
Biomedical scope only Low PubMed indexes only biomedical and life sciences literature. Queries for physics, CS, engineering, or social sciences will return no results. Users must be directed to appropriate databases.
Full-text availability Medium Only ~6 million of 36+ million articles have full text in PMC. Most articles only provide abstracts and metadata.
Upstream package dependency Low All MCP tool logic lives in @cyanheads/pubmed-mcp-server. Breaking changes in the upstream package require a container rebuild.
No local caching Low The server is stateless — every query hits the NCBI API. Repeated identical queries are not cached.
Canvas native dependencies Low Build requires Cairo, Pango, and image codec libraries. Build-time packages (build-essential, pkg-config) are purged but runtime libs remain in the image.
Generated by /repo-architecture v2.0.0 on 2026-03-22. This document is auto-generated — regenerate after significant changes.