Pubmed Clinical

pubmed-clinical-mcp is a lightweight Model Context Protocol (MCP) server for clinical biomedical literature retrieval. It gives MCP-compatible clients reusable tools for PubMed/MEDLINE search, article metadata retrieval, PubMed Central full text, full-text availability checks, related articles, clinical query building, PICO extraction, article ranking, and evidence summarization.

This project is designed for clinical evidence support and research workflows. It is not a diagnosis system, treatment recommendation system, paywall bypasser, or institutional-library automation tool.

Why This Exists

Many medical agents need reliable access to public biomedical literature, but PubMed handling often gets mixed into one-off application code. This package separates that capability into a standalone MCP server so tools like Codex, Claude Desktop, Cursor, or other MCP clients can call PubMed-focused tools directly.

Features

• PubMed/MEDLINE search through NCBI E-utilities.
• PubMed article fetching with title, abstract, authors, journal, year, DOI, PMCID, MeSH terms, publication types, and URL.
• PubMed Central open-access full-text section retrieval when legally available.
• Related PubMed article lookup through NCBI elink.
• Unpaywall DOI availability checks for legal open-access links.
• Clinical query builder for natural-language medical questions.
• Article ranking against a clinical question with relevance reasons.
• Rough PICO extraction from abstracts or article passages.
• Citation-backed evidence table and limitations summary.
• Retry/backoff on 429 and transient server failures.
• Optional local JSON cache.
• Tests use local fixtures, so CI does not need live API access.

Tool List

Tool	Purpose
build_clinical_query	Convert a natural-language clinical question into a PubMed-ready query.
search_pubmed	Search PubMed and return PMIDs plus lightweight metadata.
fetch_pubmed_articles	Fetch detailed PubMed article metadata for PMIDs.
search_and_fetch_pubmed	Build a query, search, fetch, rank, and return citations in one call.
fetch_pmc_full_text	Fetch PMC full-text sections when a PMCID is legally available.
check_full_text_availability	Check PMC and Unpaywall for legal full-text access.
find_related_articles	Find related PubMed articles using NCBI elink.
rank_articles	Rank article objects against a clinical question.
extract_pico	Extract rough population/intervention/comparator/outcome fields.
summarize_evidence	Produce an evidence table, citation-backed findings, and limitations.

Install

git clone https://github.com/jxia622/pubmed-clinical-mcp.git
cd pubmed-clinical-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Optional Environment Variables

No paid keys are required. For low-volume demos, the server can run without API keys.

export NCBI_EMAIL="[email protected]"
export NCBI_API_KEY="optional_free_ncbi_key"
export UNPAYWALL_EMAIL="[email protected]"
export PUBMED_MCP_CACHE_PATH=".cache/pubmed_clinical_mcp.json"

Notes:

• NCBI_EMAIL is recommended for NCBI E-utilities usage.
• NCBI_API_KEY is optional and raises NCBI rate limits.
• UNPAYWALL_EMAIL is required for Unpaywall checks.
• PUBMED_MCP_CACHE_PATH enables a simple local JSON cache.

Run The MCP Server

pubmed-clinical-mcp

or:

python -m pubmed_clinical_mcp.server

Example MCP Client Config

{
  "mcpServers": {
    "pubmed-clinical": {
      "command": "python",
      "args": ["-m", "pubmed_clinical_mcp.server"],
      "env": {
        "NCBI_EMAIL": "[email protected]",
        "PUBMED_MCP_CACHE_PATH": ".cache/pubmed_clinical_mcp.json"
      }
    }
  }
}

Example Tool Calls

Build a PubMed query

{
  "natural_language_question": "Why might a diabetic foot ulcer be Wagner grade 2 instead of grade 1?",
  "filters": {
    "english_only": true,
    "year_from": 2020
  }
}

Example output:

{
  "query": "(\"diabetic foot\"[Title/Abstract] OR \"diabetic foot ulcer\"[Title/Abstract]) AND (Wagner[Title/Abstract] OR classification[Title/Abstract] OR staging[Title/Abstract]) AND english[Language] AND (\"2020\"[Date - Publication] : \"3000\"[Date - Publication])",
  "explanation": [
    "Mapped diabetic foot ulcer + Wagner wording to title/abstract terms for classification and staging."
  ],
  "filters": {
    "english_only": true,
    "year_from": 2020
  }
}

Search and fetch ranked PubMed articles

{
  "clinical_question": "What evidence supports using wound depth in diabetic foot ulcer severity assessment?",
  "filters": {
    "english_only": true
  },
  "max_results": 10
}

Returns:

• query_used
• query_explanation
• ranked_articles
• citations

Fetch PMC full text

{
  "pmcid": "PMC9446755"
}

Returns parsed sections when the article is available in PubMed Central.

Architecture

flowchart LR
  Client["MCP client"] --> Server["pubmed-clinical-mcp server"]
  Server --> Query["clinical query builder"]
  Server --> PubMed["NCBI PubMed E-utilities"]
  Server --> PMC["PubMed Central XML"]
  Server --> Unpaywall["Unpaywall API"]
  Server --> Rank["ranking + PICO + summarization helpers"]
  Server --> Cache["optional JSON cache"]

Core modules:

src/pubmed_clinical_mcp/
  server.py                 # MCP tool definitions
  sources/pubmed.py         # PubMed esearch, efetch, elink
  sources/pmc.py            # PMC full-text XML parsing
  sources/unpaywall.py      # DOI open-access checks
  clinical/query_builder.py # natural language -> PubMed query
  clinical/ranking.py       # relevance ranking
  clinical/pico.py          # rough PICO extraction
  clinical/summarizer.py    # evidence table + limitations

Development

Tests use fixtures and do not call live APIs:

PYTHONPATH=src python3 -m unittest discover -s tests

Compile check:

PYTHONPATH=src python3 -m compileall src tests

API And Rate-Limit Notes

• PubMed and PMC use NCBI E-utilities.
• NCBI allows higher request rates when NCBI_API_KEY is configured.
• The server includes basic retry/backoff for 429 and transient 5xx failures.
• The cache is intentionally simple and optional. It is not a vector database.

Safety And Scope

This server:

• retrieves public biomedical literature metadata and legal open-access text;
• does not diagnose;
• does not prescribe treatment;
• does not bypass paywalls;
• does not scrape publisher websites;
• does not automate university or hospital library login;
• does not store institutional credentials.

Any clinical interpretation should be performed by qualified clinicians using the retrieved sources and appropriate guidelines.