Public Hosted Server: https://pubmed.caseyjhand.com/mcp

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

• NCBI Bookshelf results carry their own venue — bookTitle, publisherName, and docType (chapter, book, or citation) — because PubMed leaves source empty on them; the book's editors are reported in editors, apart from the chapter's own authors

• 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)

• NCBI Bookshelf chapters and whole books are returned as first-class records, not reported unavailable: recordType (journal-article, book-chapter, book) tells them apart, and a book object carries the book title, publisher, place, dates, medium, edition, series, ISBNs, book DOI, editors, and Bookshelf accession. journalInfo is absent on those records — a book title is never reported as a journal

• Journals that assign article numbers instead of page ranges often carry no pagination at all; the number is reported as journalInfo.elocationId with its journalInfo.elocationIdType (pii), never merged into journalInfo.pages and never confused with the DOI

• Opt-in whole-response ceiling: maxResponseCharacters keeps complete article records in response order until the next one would cross it, then defers the rest whole and lists their PMIDs in deferred.ids. Re-call with those PMIDs to resume exactly where the response stopped — no article is split, skipped, or duplicated. Each article is measured as the JSON record it is returned as, so a ceiling under the first article returns zero articles, the full deferred list, and the size to clear

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). One identifier per element in every branch — a DOI carrying a comma or whitespace is rejected at the schema

• 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-body, no-doi, doi-lookup-failed, no-oa, fetch-failed, parse-failed, service-error) so callers can retry or explain to users without parsing text. no-doi and doi-lookup-failed are the settled and unsettled halves of the same gap: the first means the DOI lookup ran and the record has none, the second that the lookup itself errored, so a DOI may well exist and the request is worth retrying

• An unavailable entry also carries unqueriedTiers when the chain skipped a tier this deployment has not configured and that tier could have served the id — the search was incomplete, and a deployment with those tiers configured may still resolve it

• 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 substring match at any nesting depth, e.g. ["methods", "results"]) and configurable max sections apply to PMC output. A section that matches directly is returned whole; one kept only because a nested subsection matched keeps its heading as a breadcrumb with its own text cleared

• Tables are returned as structured cells (tables[] on each PMC article — rows, caption, label, footnotes, and the enclosing section, named for back-matter and appendix tables as well as body ones), covering <floats-group>, <back> and appendix deposits alongside body tables. colspan and rowspan are expanded to one entry per grid column, so a value stays under the header it belongs to on both output surfaces; a cell spanning several columns or rows repeats across the cells it covers. A deposit with no readable markup comes back labelled with an unextractableReason rather than silently missing. Turn them off with includeTables: false

• Figures and supplementary material come back as structured entries (assets[] on each PMC article — assetType, label, caption, the enclosing section, and the <graphic>/<media> pointer exactly as deposited, which is a name inside the PMC deposit rather than a fetchable URL), covering <floats-group>, <back> and appendix placements alongside body ones. Each one lifted out of the body leaves a [Figure: <label>] / [Supplementary: <label>] marker at its position, so reading order survives the lift. Turn them off with includeAssets: false, which removes the markers with them. Prose-shaped blocks — lists, definition lists, block quotes, boxed text, preformatted blocks, displayed formulae — render into the section text at their document position instead, and no block is ever concatenated into a neighbouring sentence

• Character budgets keep context size predictable: maxCharacters caps body text per article (PMC sections and subsections, inline blocks included, plus table content — cell, caption, label and footnote text, not the Markdown grid rendered around it — and asset label, caption and pointer text; 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). Sections are served first, then tables, then assets, each spending what is left in document order until one does not fit; that entry and the rest are dropped whole rather than cut mid-row or returned with a shortened caption, and named in truncation.articles[].omittedTableNames / omittedAssetNames. Budgets run after the semantic filters, and a truncation object reports per-article and per-section character counts whenever anything was shortened

• maxResponseCharacters bounds the whole response instead of each body: every field of a returned record counts (abstract, references, metadata, body), one ledger across PMC-, Europe PMC-, and Unpaywall-served articles. Articles past the ceiling are deferred whole, with their ids — in the branch they were requested under — in deferred.ids for a follow-up call

• 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)

• NCBI Bookshelf chapters and whole books cite in their own form in every style — Vancouver's In: … editors contribution pattern, APA's chapter-in-edited-book, MLA's edited by, BibTeX @incollection / @book, RIS CHAP / BOOK — carrying the book title, editors, publisher, place, ISBNs and Bookshelf URL

• An article with no page range cites by its electronic article locator in each style's own convention — Vancouver's trailing pii: note, APA's Article <n>, MLA's art. <n>, biblatex eid, RIS C7 — rather than dropping it or writing it into a page field

• 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 — or, for an NCBI Bookshelf record, its book title, publisher, and doc type in place of the empty source

• Results returned in NCBI's relevance order

• Falls back to Europe PMC, then OpenAlex, when NCBI cannot answer; the response names which provider served it. A request no provider can answer fails with a typed all_providers_failed error instead of an empty result

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

• Bibliographic fields cannot contain a pipe (|) or a line break — ECitMatch's wire format is pipe-delimited, so those characters are rejected at the schema; the free-form key label is exempt

• 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)

• One identifier per array element, checked against idType before the request — a packed value like "23193287,37952131" is rejected rather than expanded into extra records, since a comma is the converter's list delimiter in any encoding

• 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.