# ryogena-pubmed-mcp

A small, focused **Model Context Protocol** server that exposes
[NCBI PubMed](https://pubmed.ncbi.nlm.nih.gov/) as MCP tools, so any
MCP-compatible client (Claude Desktop, Claude Code, custom agents) can
search the literature, fetch abstracts, walk the citation graph, and look
up an author's publications without leaving the chat.

No API key required. An optional `NCBI_API_KEY` raises the rate limit
from 3 → 10 requests/sec.

## Tools

| Tool | What it does |
|---|---|
| `search_pubmed(query, max_results, sort)` | Free-text or full-syntax PubMed query. Returns title, authors, journal, pubdate, DOI, PubMed URL. |
| `fetch_article(pmid)` | Full abstract for one PMID, with section labels preserved (Background / Methods / Results / Conclusions). |
| `find_related(pmid, max_results)` | NCBI's "related articles" neighbors — walk the citation graph from any paper. |
| `search_by_author(author, max_results, sort)` | Author publication list using the `[au]` field qualifier. |

All tools are read-only; PubMed itself is read-only.

## Install

```bash
pip install ryogena-pubmed-mcp
```

Or from source:

```bash
git clone https://github.com/KyleVick4/pubmed-mcp
cd pubmed-mcp
pip install -e .
```

## Configure in Claude Desktop

Edit your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pubmed": {
      "command": "python",
      "args": ["-m", "pubmed_mcp"],
      "env": {
        "NCBI_API_KEY": "<optional>",
        "NCBI_EMAIL":   "<optional, recommended by NCBI>"
      }
    }
  }
}
```

Restart Claude Desktop. The `pubmed` server should show up in the MCP
panel with four tools.

## Configure in Claude Code

```bash
claude mcp add pubmed -- python -m pubmed_mcp
```

## Try it

Once wired up:

> *Find me the three most-cited papers on JAK2 V617F selectivity from 2023, then pull the abstract of the top hit.*

Claude will plan a `search_pubmed` → `fetch_article` chain and cite each
paper with its DOI and PubMed URL.

## Verify the server before debugging your client

Use the MCP Inspector — it's the fastest way to see if the server starts
cleanly and the tools register:

```bash
npx @modelcontextprotocol/inspector python -m pubmed_mcp
```

## Run the tests

The test suite is hermetic — no NCBI requests, no network. Every HTTP
call is intercepted by `httpx.MockTransport`.

```bash
pip install -e ".[dev]"
pytest -v
```

## Why this exists

I built [Pico](https://www.ryogena.com), a closed-source AI-native drug
discovery platform, with [its own MCP server](https://www.ryogena.com)
that exposes molecule and assay tools to Claude Desktop. Building
*ryogena-pubmed-mcp* in the open lets me share the integration patterns I use —
slim LLM-friendly projections, hermetic test design, error-envelope
contracts — without exposing the domain code.

If you're building an MCP server and want a tiny reference, the
[`server.py`](pubmed_mcp/server.py) and
[`tests/test_tools.py`](tests/test_tools.py) files together are about
500 lines and demonstrate the full pattern.

## License

MIT — see [LICENSE](LICENSE).