pubmed-mcp
Search, retrieve, audit, and open-access-check PubMed literature via NCBI E-utilities with strict source fidelity.
Search PubMed with Boolean/MeSH/field-tag queries, sorting, date bounds, pagination, query translation, and optional Entrez History tokens (
search_pubmed,pubmed_search).Fetch exact records/abstracts for up to 200 PMIDs, including per-record status,
not_foundPMIDs, provenance, and flagged missing fields (fetch_abstracts,pubmed_fetch).Retrieve one PMID as normalized data or raw XML with SHA-256 integrity hash (
pubmed_get).Batch-fetch large result sets from PMID lists or WebEnv/query_key in chunks up to 200 (
pubmed_batch_fetch).Check open-access status for up to 100 PMIDs: OA PDF, landing page only, no OA found, or unchecked (
check_access).Combine a PubMed search with open-access classification counts/lists for up to 100 hits (
search_with_access).Download legal open-access PDFs for up to 50 PMIDs, verify real PDF headers, and skip paywalled papers (
download_pdfs).Get NCBI database metadata, update date, record count, and field tags (
pubmed_database_info).
Provides tools for searching PubMed via NCBI E-utilities, fetching abstracts and metadata, checking open-access availability, and downloading open-access PDFs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pubmed-mcp Search PubMed for RCTs on GLP-1 agonists and weight loss, then fetch abstracts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Why this exists
Related MCP server: PubMed MCP Server
Most PubMed wrappers either invent missing metadata or bury the original NCBI response. This one does neither. Every field comes from the source. If PubMed left something out, you see it. That makes the output usable in PRISMA workflows and audit trails. First Pubmed MCP from Med Student in Pakistan from SZMC RYK
Architecture
flowchart TB
subgraph Client["MCP Clients"]
A[Claude Desktop]
B[Cursor / Antigravity]
C[OpenCode]
D[Any MCP client]
end
subgraph Server["pubmed-mcp"]
direction TB
T1[pubmed_search]
T2[pubmed_get]
T3[pubmed_fetch / batch_fetch]
T4[check_access / download_pdfs]
T5[pubmed_database_info]
NC["ncbi_client.py<br/>rate-limit · retry · provenance"]
ACC["access.py<br/>Unpaywall + PMC"]
end
subgraph NCBI["NCBI E-utilities"]
ES[esearch.fcgi]
EF[efetch.fcgi]
EI[einfo.fcgi]
end
subgraph External["Open Access"]
UP[Unpaywall]
PMC[PubMed Central]
end
Client --> Server
T1 & T2 & T3 & T5 --> NC
T4 --> ACC
NC --> NCBI
ACC --> UP
ACC --> PMC
style Client fill:#e0f2fe,stroke:#0284c7
style Server fill:#f0fdfa,stroke:#0d9488
style NCBI fill:#fef3c7,stroke:#d97706
style External fill:#fce7f3,stroke:#db2777Data flow (search → records)
flowchart LR
Q[User Query] --> S[pubmed_search]
S --> H{use_history?}
H -->|yes| WH[WebEnv + QueryKey]
H -->|no| PMIDs[PMID list]
WH --> BF[pubmed_batch_fetch]
PMIDs --> BF
PMIDs --> GET[pubmed_get]
BF --> NORM["Normalized records<br/>+ missingness flags"]
GET --> NORM
NORM --> PROV[Provenance block]
NORM --> RET[Retraction / Erratum flags]
style Q fill:#e0f2fe
style NORM fill:#ccfbf1
style PROV fill:#fef3c7
style RET fill:#fee2e2Guarantees
Guarantee | Meaning |
Source fidelity | Every field comes directly from the NCBI E-utilities response. Nothing is inferred, guessed, paraphrased, or enriched from external sources. |
Missingness flagged | A field PubMed does not provide is returned as the literal string |
Not-found reported | PMIDs requested but not returned by NCBI are listed in |
Provenance on every record | Each normalized record carries a |
Anti-inference |
|
No paywall bypass | Only legally open-access copies (PubMed Central, Unpaywall gold/green) are indexed and downloaded. |
Stdout reserved for MCP | In stdio mode, stdout is reserved for the MCP protocol; all logging goes to stderr. |
What this is not
No full-text extraction beyond legally open PDFs
No evidence-level grading (CEBM/GRADE) added
No silent enrichment from Crossref, OpenAlex, Semantic Scholar, or other databases
No paywall bypass
No LLM-based abstract completion or metadata inference
Install
pip install pubmed-access-mcpOr run without installing:
uvx pubmed-access-mcpTools grouped by phase / purpose
Phase 1 — Evidence provenance & search snapshots
Tool | What it does |
| NCBI einfo for a database (field list, counts, last update). |
| Save a search query + parameters as a named snapshot for reproducible retrieval. |
| Retrieve a previously created search snapshot by ID. |
| List existing snapshots (paginated). |
Phase 2 — Bibliographic exports & download audit
Tool | What it does |
| Export records in RIS format (reference managers). |
| Export records in BibTeX format. |
| Export records as CSV. |
| Export records as JSON. |
Phase 3 — Source-linked structured evidence tables
Tool | What it does |
| Build a structured evidence table from records or a snapshot. Every cell carries value + status + optional source quote. |
Phase 4 — Europe PMC, deduplication, citation chase, retraction monitoring
Tool | What it does |
| Search Europe PMC (complementary to PubMed). |
| Fetch a single Europe PMC record by ID. |
| Deduplicate records by PMID / DOI / title matching. |
| Trace citations forward/backward for a set of PMIDs. |
| Check PMIDs for retraction / erratum notices via NCBI link data. |
Phase 5 — Offline evaluation & regression benchmark
Tool | What it does |
| Validate a normalized record against the anti-inference guarantee; returns |
Core retrieval tools (all phases)
Tool | What it does |
| Search PubMed via NCBI esearch. Returns PMIDs, total match count, query translation, and Entrez History tokens ( |
| Fetch a single normalized record by PMID, with full provenance. |
| Fetch multiple PMIDs in one call (internally chunked, max 200 per chunk). |
| Retrieve large result sets via PMID list or Entrez History, chunked at |
Retrieving full result sets (> 200 records)
pubmed_search returns at most max_results PMIDs per call (default 20, capped at MAX_SEARCH = 9999). To retrieve all matching records when total_matches exceeds that:
# Step 1: Search with Entrez History enabled
result = server.pubmed_search(
query="your PubMed query",
use_history=True, # stores search on NCBI Entrez History server
max_results=200, # or higher, up to 9999
)
total_matches = result["search"]["count"] # total matching records
webenv = result["webenv"] # Entrez WebEnv token
query_key = result["query_key"] # Entrez QueryKey token
# Step 2: Batch-fetch all records in chunks of 200
all_records = server.pubmed_batch_fetch(
webenv=webenv,
query_key=query_key,
total_records=total_matches,
batch_size=200, # max 200 per chunk
)pubmed_batch_fetch iterates retstart from 0 to total_records in chunks of batch_size, returning per-batch results, per-record statuses, and not_found PMIDs.
Examples
Runnable, copy-pasteable snippets for real workflows. No secrets, no real API keys, no emails — every file uses placeholders only.
Example | Description |
Full-retrieval pattern for systematic reviews: | |
Minimal end-to-end smoke test: search → normalized single record → anti-inference benchmark check. |
Each example declares the anti-inference guarantee (false_inference_count == 0) and documents provenance statuses (directly_sourced / not_returned_by_ncbi).
Open-access PDFs
Sources: Unpaywall (DOI) and PubMed Central (PMCID). Set UNPAYWALL_EMAIL or NCBI_EMAIL. NO_OPEN_ACCESS_FOUND means no legal free copy is indexed — it does not mean an institution cannot reach the paper. Every downloaded file is checked for a real %PDF header. Bot-check pages are rejected. Default folder: ~/pubmed_pdfs (override with PUBMED_PDF_DIR). No paywall bypass.
MCP client setup
After pip install
{
"mcpServers": {
"pubmed-scraper": {
"command": "pubmed-access-mcp",
"args": [],
"env": {
"NCBI_EMAIL": "you@example.com",
"UNPAYWALL_EMAIL": "you@example.com"
}
}
}
}With uvx (no install)
{
"mcpServers": {
"pubmed-scraper": {
"command": "uvx",
"args": ["pubmed-access-mcp"],
"env": {
"NCBI_EMAIL": "you@example.com",
"UNPAYWALL_EMAIL": "you@example.com"
}
}
}
}OpenCode
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"pubmed-scraper": {
"type": "local",
"command": ["uvx", "pubmed-access-mcp"],
"environment": {
"NCBI_EMAIL": "you@example.com",
"UNPAYWALL_EMAIL": "you@example.com"
}
}
}
}Optional env vars: NCBI_API_KEY (raises rate limit), NCBI_TOOL. Keep real keys in your global config, never in a committed file.
Deploy (Google Cloud Run)
Free tier covers ~2 M requests/month with scale-to-zero.
export NCBI_EMAIL="you@example.com"
export UNPAYWALL_EMAIL="you@example.com"
export NCBI_API_KEY="your-key" # optional
chmod +x deploy.sh
./deploy.sh # or ./deploy.sh my-project us-east1After deploy the endpoint looks like:
https://pubmed-mcp-HASH-REGION.a.run.app/mcpPoint any MCP client that supports remote servers at that URL.
One-click public tunnel (Windows):
run_cloudflare_tunnel.batDevelopment
git clone https://github.com/ahsanmandhar-ui/pubmed-mcp.git
cd pubmed-mcp
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python tests/test_server.py # offline
python tests/test_access.pyRun the full offline test suite:
python -m pytest tests/ -vAll 68 tests pass with false_inference_count == 0.
Limitations
Abstracts only. Full text is not returned (unless the paper is in the PMC open-access subset and you download the PDF).
Search quality depends on your query. Always check
query_translation.Open-access coverage varies; some publishers block automated downloads.
Live network behaviour is not covered by the offline test suite.
License
Apache License 2.0 — see LICENSE. Copyright © ahsanmandhar-ui.
Available Tools
10 toolscheck_accessA
Classify each PMID as open-access PDF, open-access landing page only, no open access found (likely paywalled), or unchecked.
Uses DOI -> Unpaywall and PMCID -> PubMed Central. 'no_open_access_found' means no legal free copy is indexed; it does not prove the paper cannot be reached through an institution. Max 100 PMIDs per call. Needs UNPAYWALL_EMAIL (or NCBI_EMAIL) for the Unpaywall lookup; without it only PubMed Central links are found.
Inputs: pmids (required).
download_pdfsA
Download open-access PDFs for the given PMIDs (max 50) as PMID.pdf. Paywalled papers are skipped, never bypassed.
folder: absolute path, or a sub-folder name under PUBMED_PDF_DIR (default ~/pubmed_pdfs). Every file is verified to be a real PDF (starts with %PDF); HTML login/bot-check pages are rejected and reported as failed.
Inputs: pmids (required), folder.
fetch_abstractsA
Fetch exact PubMed records (NCBI efetch) for up to 200 PMIDs.
Per record: pmid, title, authors, journal, pub_date, doi, publication_types, has_retraction_notice,
abstract (structured abstracts keep their section labels), url.
Any field PubMed does not provide is the literal string 'Data not provided in PubMed abstract'.
PMIDs NCBI did not return are listed in not_found. Never infer or complete missing text.
Inputs: pmids (required).
pubmed_batch_fetchA
Batch fetch PubMed records in chunks supporting long PMID lists (>200) or NCBI Entrez History.
Supports two retrieval modes:
Direct PMID batching: Accepts an arbitrary list of PMIDs, chunking them into batch_size (max 200).
Entrez History batching: Accepts webenv and query_key from a prior pubmed_search(..., use_history=True), iterating retstart up to total_records in chunks of batch_size.
Args: pmids: Optional list of PMIDs (arbitrary length; chunked into batch_size). webenv: Optional NCBI WebEnv token from a prior pubmed_search(..., use_history=True). query_key: Optional NCBI QueryKey token from a prior pubmed_search. retstart: Starting offset for pagination (default 0). total_records: Total records to retrieve in Entrez History mode (if omitted, queries history count). batch_size: Number of records per chunk (1-200, default 200).
Returns: Comprehensive batch execution report, per-batch results, per-record statuses ('status': 'success'), not_found PMIDs, and audit provenance.
Inputs: pmids, webenv, retstart, query_key, +2 more.
pubmed_database_infoA
Get metadata, last update date, record count, and search field tags for an NCBI database (default: 'pubmed').
Provides audit-grade database metadata and field definitions directly from NCBI EInfo.
Inputs: db.
pubmed_fetchA
Fetch exact PubMed records (NCBI efetch) with per-record status and provenance.
Every field comes strictly from the NCBI response; missing fields are flagged and never inferred. Returns records with 'status': 'success' and unretrieved items with 'status': 'not_found'.
Inputs: pmids (required).
pubmed_getA
Retrieve a single PubMed record by PMID in normalized mode or raw verbatim XML.
Args: pmid: PubMed identifier (1-9 digits). mode: 'normalized' (default) returns deterministic schema with structured missingness indicators; 'raw' returns verbatim XML with SHA-256 integrity hash for auditing.
Inputs: pmid (required), mode.
pubmed_searchB
Search PubMed (NCBI esearch) with reproducibility object, query translation, and audit provenance.
Args: query: PubMed query; supports field tags, MeSH, and Boolean logic. max_results: 1-200 (default 20). start: Result offset / retstart for pagination (default 0). sort: 'relevance' or 'pub_date' (newest first). date_from / date_to: Optional publication-year bounds. use_history: If True, stores search on NCBI Entrez History server (returns webenv & query_key).
Inputs: query (required), sort, start, date_to, +3 more.
search_pubmedB
Search PubMed (NCBI esearch) and return PMIDs exactly as NCBI returns them.
Args:
query: PubMed query; supports field tags, MeSH and Boolean, e.g.
'"hypertrophic cardiomyopathy"[MeSH] AND mavacamten[tiab] AND randomized controlled trial[pt]'.
max_results: 1-200 (default 20). total_matches reports the full hit count.
sort: 'relevance' or 'pub_date' (newest first).
date_from / date_to: optional publication-year bounds (e.g. 2018, 2025).
Returns pmids, total_matches and query_translation (how PubMed interpreted the query; log it for reproducibility).
Inputs: query (required), sort, date_to, date_from, +1 more.
search_with_accessB
Run a PubMed search, then report for every hit whether a legal open-access PDF exists or the paper looks paywalled.
max_results is capped at 100 here. Returns query_translation and total_matches (as search_pubmed) plus counts and four lists: open_access_pdf, open_access_landing_page_only, no_open_access_found, unchecked.
Inputs: query (required), sort, date_to, date_from, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
pubmed_search and search_pubmed are functionally near-identical (both run NCBI esearch and return PMIDs/query translation), and pubmed_fetch, fetch_abstracts, and pubmed_batch_fetch all wrap efetch with only minor output differences. check_access vs search_with_access also overlap, leaving several boundaries unclear despite good descriptions.
Names mix a pubmed_ prefix (pubmed_search, pubmed_fetch, pubmed_get, pubmed_batch_fetch, pubmed_database_info) with bare verb_noun forms (fetch_abstracts, check_access, download_pdfs) and an unconventional reversed form (search_pubmed). The search pair differing only by word order is especially confusing.
Ten tools is a reasonable scope for a PubMed retrieval server, but several tools are redundant variants of the same underlying operation rather than distinct capabilities. The count itself is fine; the duplication is the issue.
The surface covers the core retrieval lifecycle well: search, single/multi/batch fetch, normalized or raw output, access classification, and PDF download. Minor gaps exist (no citation/related-article or export formats like RIS/BibTeX), which agents can work around.
Related MCP Connectors
Search PubMed/Europe PMC, fetch articles and full text (PMC/EPMC/Unpaywall), citations, MeSH terms.
Search biomedical literature, get article details, find related articles, and explore MeSH terms
PubMed MCP — wraps the NCBI E-utilities API (biomedical literature, free, no auth)
Search biomedical papers, inspect publication records, and traverse citation or semantic graphs.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables searching and retrieving scientific articles from PubMed using NCBI E-utilities API with features like rate limiting and caching.3MIT
- FlicenseNot gradedqualityCmaintenanceEnables searching PubMed's biomedical literature database and retrieving article metadata, abstracts, and full content through the E-utilities API. Supports advanced queries, batch operations, and multiple output formats with automatic rate limiting.2-
- AlicenseNot gradedqualityCmaintenanceEnables searching and retrieving biomedical literature from PubMed via the NCBI E-utilities API.112 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables PubMed literature search, metadata retrieval, BibTeX export, and evidence table generation for biomedical research agents.2MIT