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

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

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:

Rate limits

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

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.