mcp-pubmed

A Model Context Protocol (MCP) server that gives Claude (or any MCP-compatible AI) direct access to PubMed and PubMed Central via the free NCBI E-utilities API.

No subscription required. No third-party service. Pure NCBI.

---

Features

Tool	Description
search_pubmed	Search articles by keyword, with filters for date range, article type, and sort order. Supports full PubMed query syntax.
get_article	Retrieve complete metadata for a single article by PMID (abstract, authors, MeSH terms, keywords, DOI, PMC link).
get_full_text	Download the full text from PubMed Central when the article is open-access.
get_related_articles	Find articles related to a given PMID using NCBI's similarity algorithm.
search_by_author	List all articles published by a specific author, sorted by most recent.

---

Requirements

• Python 3.11 or higher
• pip

---

Installation

1 — Clone the repository

git clone https://github.com/benoitleq/mcp-pubmed.git
cd mcp-pubmed

2 — Create a virtual environment

python -m venv .venv

Activate it:

• Windows (PowerShell) : .venv\Scripts\Activate.ps1
• Windows (CMD) : .venv\Scripts\activate.bat
• macOS / Linux : source .venv/bin/activate

3 — Install dependencies

pip install -r requirements.txt

4 — (Optional) Set your NCBI API key

Without a key the NCBI API is limited to 3 requests/second. With a free key you get 10 requests/second.

Get your key at https://www.ncbi.nlm.nih.gov/account/ → Settings → API Key Management.

Copy the example env file and add your key:

cp .env.example .env
# then edit .env and uncomment the NCBI_API_KEY line

Or set it directly in your shell:

export NCBI_API_KEY=your_key_here      # macOS / Linux
$env:NCBI_API_KEY = "your_key_here"   # Windows PowerShell

---

Configure Claude Desktop

Edit claude_desktop_config.json (location depends on your OS):

OS	Path
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Add the following block inside the "mcpServers" object:

{
  "mcpServers": {
    "pubmed": {
      "command": "python",
      "args": ["C:/path/to/mcp-pubmed/main.py"],
      "env": {
        "NCBI_API_KEY": "your_key_here"
      }
    }
  }
}

Windows tip: use forward slashes or double backslashes in the path. If python is not on your PATH, use the full path to your virtual environment: "C:/path/to/mcp-pubmed/.venv/Scripts/python.exe"

Restart Claude Desktop. You should see the 5 PubMed tools available.

---

Configure Claude Code (VS Code / CLI)

Run this command from the project root:

claude mcp add pubmed python main.py

Or add it manually to your Claude Code settings (.claude/settings.json):

{
  "mcpServers": {
    "pubmed": {
      "command": "python",
      "args": ["main.py"],
      "env": {
        "NCBI_API_KEY": "your_key_here"
      }
    }
  }
}

---

Usage examples

Once connected, just ask Claude naturally:

Search for recent meta-analyses on SGLT2 inhibitors and heart failure.

Find the 5 latest meta-analyses on metformin and cancer.

Find all articles published by Topol EJ since 2020.

Get the abstract for PMID 33982811.

Is the full text of PMID 34591945 available?

Find articles related to PMID 31475795.

PubMed query syntax

The search_pubmed tool accepts standard PubMed query syntax:

Example	Meaning
"heart failure"[MeSH]	Exact MeSH term
metformin[tiab]	Word in title or abstract
Smith J[au]	Articles by author
2020:2024[pdat]	Publication date range
"Randomized Controlled Trial"[pt]	Filter by publication type
AND, OR, NOT	Boolean operators

---

Rate limits

Situation	Limit
No API key	3 requests / second
With API key	10 requests / second

The server handles 429 rate-limit errors and 5xx server errors automatically with up to 3 retries and exponential back-off.

---

Project structure

mcp-pubmed/
├── main.py            # MCP server — all tools defined here
├── requirements.txt   # Python dependencies
├── pyproject.toml     # Package metadata
├── .env.example       # Environment variable template
└── README.md

---

How it works

Claude ──MCP── main.py ──HTTPS── NCBI E-utilities API
                                 ├── esearch.fcgi  (search)
                                 ├── efetch.fcgi   (fetch records / full text)
                                 └── elink.fcgi    (related articles)

1. Claude calls a tool (e.g. search_pubmed).
2. main.py builds a request to the appropriate NCBI endpoint.
3. The XML/JSON response is parsed and formatted as plain text.
4. Claude receives the result and presents it to you.

---

MCP vs Skill — which approach to choose?

There are two ways to give Claude access to PubMed:

1. This project — an MCP server (Python process, explicit tools)
2. A Skill — a Markdown prompt file that instructs Claude to call the NCBI API directly via its built-in web_fetch capability (see e.g. pubmed-skill)

Comparison

	MCP (this project)	Skill (prompt file)
Setup	Python 3.11 + venv + dependencies + config in claude_desktop_config.json	Copy one .md file — done
Maintenance	Server process to start and keep running	Nothing to maintain
Portability	Must be configured in every Claude client	Works anywhere Claude has web access
Reliability	Deterministic — explicit retry logic, error handling, XML parsing	Depends on Claude's interpretation of the prompt
Power	Full control: pagination, caching, auth, complex post-processing	Limited to what Claude can do in a single prompt turn
Sharing	Distributable as a Python package or Docker image	Just share the .md file
Auditability	Code is explicit, testable, versionable	Behavior may vary across Claude versions

When to choose MCP

• You need guaranteed, reproducible behavior on every call
• You are building a tool for a team or an application (not just personal use)
• You need complex logic: pagination, caching, structured output, authentication
• You want to expose PubMed to non-Claude clients via the MCP standard

When to choose a Skill

• Personal use in Claude Desktop or Claude Code — you just want it to work
• You want zero friction: no installation, no configuration, no process to manage
• The task is occasional and correctness variations are acceptable

Bottom line

For solo use, a Skill is simpler and good enough. For production, teams, or complex workflows, MCP is more robust.

---

Troubleshooting

"No module named mcp" → Make sure your virtual environment is activated and you ran pip install -r requirements.txt.

"Could not connect to NCBI" → Check your internet connection. NCBI is at eutils.ncbi.nlm.nih.gov.

Rate limit errors (429) → Add an NCBI API key (see above).

Claude does not see the tools → Check that the path in claude_desktop_config.json is absolute and correct. → Restart Claude Desktop after any config change.

---

License

MIT — free for personal and commercial use.

---

Acknowledgements

Built on the NCBI E-utilities API (free, no subscription required) and the Model Context Protocol by Anthropic.