pubmed-mcp-server

Tools

11 tools for working with PubMed, PubMed Central, and Europe PMC data:

`pubmed_search_articles`

Search PubMed with full NCBI query syntax and filters.

• Free-text queries with PubMed's full boolean and field-tag syntax
• Field-specific filters: author, journal, MeSH terms, language, species
• Common filters: has abstract, free full text
• Date range filtering by publication, modification, or Entrez date
• Publication type filtering (Review, Clinical Trial, Meta-Analysis, etc.)
• Sort by relevance, publication date, author, or journal
• Pagination via offset for paging through large result sets
• Optional brief summaries for top N results via ESummary
• Returns the original query plus the fully applied PubMed query and normalized filter metadata

`pubmed_fetch_articles`

Fetch full article metadata by PubMed IDs.

• Batch fetch up to 200 articles at once (auto-switches to POST for batches >= 100)
• Returns structured data: title, abstract, authors with deduplicated affiliations, journal info, DOI
• Direct links to PubMed and PubMed Central (when available)
• Optional MeSH terms, grant information, and publication types
• Handles PubMed's inconsistent XML (structured abstracts, missing fields, varying date formats)

`pubmed_fetch_fulltext`

Fetch full-text articles via a three-stage chain: NCBI PMC EFetch → Europe PMC `fullTextXML` → Unpaywall.

• Accepts exactly one of `pmcids` (direct PMC IDs), `pmids` (PubMed IDs, auto-resolved), or `dois` (auto-resolved to PMC via the ID Converter; preprints and EPMC-only OA fall through to Europe PMC / Unpaywall)
• NCBI PMC and Europe PMC both return structured JATS; output records origin via `viaSource: "pmc" | "europepmc" | "unpaywall"`
• Europe PMC layer (enabled by default; disable with `EUROPEPMC_ENABLED=false`) recovers PMC-counterpart records that NCBI PMC EFetch missed, and resolves DOI input to PMC counterparts when one exists. EPMC's `fullTextXML` is PMC-keyed, so preprints (PPR), patents (PAT), and Agricola (AGR) are reachable via `pubmed_europepmc_search` for metadata but have no full text via this chain.
• Unpaywall layer (enabled by setting `UNPAYWALL_EMAIL`) resolves DOIs to legal OA copies; extracts HTML landing pages to Markdown via Defuddle or PDFs to text via unpdf
• Discriminated output contract — `source: "pmc"` (structured sections, regardless of whether it came from PMC or EPMC) or `source: "unpaywall"` (best-effort body + `contentFormat`: `html-markdown` or `pdf-text`)
• Structured unavailable reasons (`not-found`, `no-pmc-fallback-disabled`, `no-epmc-fulltext`, `no-doi`, `no-oa`, `fetch-failed`, `parse-failed`, `service-error`) so callers can retry or explain to users without parsing text
• Each `unavailable` entry carries `idType` (`pmid` / `pmcid` / `doi`) and `triedTiers` — per-tier outcomes (`not-attempted`, `miss`, `no-fulltext`, `service-error`, …) in execution order, so callers can see which stage failed and why
• Section filtering by title (case-insensitive match, e.g. `["methods", "results"]`) and configurable max sections apply to PMC output
• Character budgets keep context size predictable: `maxCharacters` caps body text per article (PMC sections and subsections, or the Unpaywall body), `maxCharactersPerSection` caps a single PMC section, and `overflowMode` picks between `truncate` (fill sections in document order) and `outline` (split the budget evenly so every heading survives with an excerpt). Budgets run after the semantic filters, and a `truncation` object reports per-article and per-section character counts whenever anything was shortened
• Up to 10 articles per request

`pubmed_europepmc_search`

Search Europe PMC (EBI/EMBL-EBI), a broader open-access biomedical corpus than PubMed alone.

• Surfaces records PubMed search can't reach — preprints (`source: PPR`), patents (`source: PAT`), Agricola (`source: AGR`), plus everything in PubMed (`MED`) and PMC (`PMC`). On recent queries this can mean dozens of relevant hits with zero PubMed overlap.
• Default sources `["MED", "PMC", "PPR"]`; pass `sources` to include `PAT` / `AGR`
• Cursor-based pagination via `cursorMark` (unlike `pubmed_search_articles`, which uses offset) — `*` for the first page, return `nextCursorMark` for the next
• Output discriminator on `source` plus optional `pmid` / `pmcId` / `doi` cross-walking
• `abstractSnippet` is capped at 400 characters to keep a page bounded; `abstractTruncated` says whether it was cut, and `pubmed_europepmc_fetch` returns the whole abstract for the records worth reading in full
• Disabled when `EUROPEPMC_ENABLED=false`; tool is not registered in that case

`pubmed_europepmc_fetch`

Fetch complete Europe PMC records by `source` + `epmcId`, the detail counterpart to `pubmed_europepmc_search`.

• Returns the full, untruncated abstract as display-ready plain text — markup stripped, HTML entities decoded
• Addressed by the `source` and `epmcId` of a search hit, the only identifier preprint (`PPR`), patent (`PAT`), and Agricola (`AGR`) records reliably carry — `pubmed_fetch_articles` needs a PMID and `pubmed_fetch_fulltext` needs a PMCID, PMID, or DOI
• Up to 25 records per call, resolved in a single Europe PMC request
• Pairs unresolved requests back to the caller in `notFound` instead of failing the batch
• Disabled when `EUROPEPMC_ENABLED=false`; tool is not registered in that case

`pubmed_format_citations`

Generate formatted citations for articles.

• Five citation styles: APA 7th, MLA 9th, BibTeX, RIS, Vancouver (ICMJE/NLM)
• Request multiple styles per article in a single call
• Hand-rolled formatters — zero external dependencies, fully Workers-compatible
• Up to 50 articles per request
• Reports formatted counts and unavailable PMIDs for partial-result handling

`pubmed_find_related`

Find articles related to a source article via ELink.

• Three relationship types: `similar` (content similarity), `cited_by`, `references`
• Results enriched with title, authors, publication date, and source via ESummary
• Results returned in NCBI's relevance order

`pubmed_spell_check`

Spell-check a biomedical query using NCBI's ESpell.

• Returns the original query, corrected query, and whether a suggestion was found
• Useful for query refinement before searching

`pubmed_lookup_mesh`

Search and explore the MeSH (Medical Subject Headings) vocabulary.

• Search MeSH terms by name with exact-heading matching
• Detailed records with tree numbers, scope notes, and entry terms by default
• Useful for building precise PubMed queries with controlled vocabulary

`pubmed_lookup_citation`

Resolve partial bibliographic references to PubMed IDs via NCBI ECitMatch.

• Match citations by journal, year, volume, first page, and/or author name
• More fields = better match accuracy; at least one field required
• Batch up to 25 citations per request
• Deterministic matching — more reliable than free-text search for known references
• Returns explicit `matched`, `not_found`, and `ambiguous` statuses with recovery detail

`pubmed_convert_ids`

Convert between article identifiers (DOI, PMID, PMCID) using the PMC ID Converter API.

• Batch up to 50 IDs per request
• Accepts DOIs, PMIDs, or PMCIDs (all IDs must be the same type)
• Only resolves articles indexed in PubMed Central
• Per-ID success/error reporting — partial batches return resolved mappings alongside structured errors for unresolvable IDs, not a batch-level failure

Resource and prompt

Features

Built on `@cyanheads/mcp-ts-core`:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Pluggable auth (`none`, `jwt`, `oauth`)
• Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
• Structured logging with optional OpenTelemetry tracing
• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

PubMed-specific:

• Complete NCBI E-utilities integration (ESearch, EFetch, ESummary, ELink, ESpell, EInfo, ECitMatch) plus PMC ID Converter
• Sequential request queue with configurable delay for NCBI rate limit compliance
• NCBI-specific XML parser with `isArray` hints for PubMed's inconsistent XML structure
• Hand-rolled citation formatters (APA, MLA, BibTeX, RIS, Vancouver) — zero deps, Workers-compatible

Agent-friendly output:

• Provenance on every response — source labels, license fields, best-effort warnings on Unpaywall results, and effective-query echo on searches so agents can reason about trust
• Graceful partial failure — batch tools return per-item success/error rows instead of failing the request, with structured status codes and actionable next-step text
• Discriminated output contracts — `source: "pmc" | "unpaywall"`, typed `unavailable` reasons, `viaSource` and `triedTiers` fields — callers branch on data, not string parsing

Getting started

Public Hosted Instance

A public instance is available at `https://pubmed.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "pubmed-mcp-server": {
      "type": "streamable-http",
      "url": "https://pubmed.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "pubmed-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/pubmed-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NCBI_API_KEY": "your-key-here"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "pubmed-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/pubmed-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NCBI_API_KEY": "your-key-here"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "pubmed-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/pubmed-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.2 or higher.
• Optional: NCBI API key for higher rate limits (10 req/s vs 3 req/s).

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd pubmed-mcp-server

3. Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. Key environment variables:

Running the server

Local development

• Build and run the production version:

# One-time build
  bun run rebuild

  # Run the built server
  bun run start:http
  # or
  bun run start:stdio

• Run checks and tests:

bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite

Project structure

Development guide

See `CLAUDE.md` for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no `try/catch` in tool logic
• Use `ctx.log` for logging, `ctx.state` for storage
• Register new tools and resources in the `createApp()` arrays

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

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