# pubmed-mcp

[Polski](README.pl.md)

MCP server exposing NCBI PubMed/PMC APIs: E-utilities (search, summaries, full records, links, database info, spelling, citation matching), BioC full text, the Literature Citation Exporter, and the PMC ID Converter.

## Table of contents

- [Tools](#tools)
- [Environment variables](#environment-variables)
- [Wiring it up](#wiring-it-up)
- [Local run](#local-run)

## Tools

| Tool | Parameters | Description |
|------|-----------|------|
| `search_pubmed` | `term: str, db: str = "pubmed", retmax: int = 20, retstart: int = 0, sort: Optional[str] = None, mindate: Optional[str] = None, maxdate: Optional[str] = None, datetype: Optional[str] = None` | ESearch — matching UIDs and total count |
| `get_summaries` | `db: str, ids: str, select: str = "*"` | ESummary — document metadata for a list of UIDs |
| `fetch_records` | `db: str, ids: str, rettype: str, retmode: "xml"\|"text" = "text", max_chars: int = 20000` | EFetch — full records (abstracts, FASTA, GenBank, etc.) |
| `find_related_links` | `ids: str, dbfrom: str = "pubmed", db: str = "pubmed", linkname: Optional[str] = None, cmd: str = "neighbor"` | ELink — related/cross-referenced records |
| `get_database_info` | `db: Optional[str] = None` | EInfo — list of Entrez databases, or fields/links for one database |
| `global_query_counts` | `term: str` | EGQuery — result counts across all Entrez databases |
| `spelling_suggestions` | `db: str, term: str` | ESpell — spelling-corrected search term |
| `match_citations` | `citations: str` | ECitMatch — batch citation-to-PMID matching |
| `get_full_text` | `id: str, id_type: "pmid"\|"pmcid" = "pmid", encoding: "unicode"\|"ascii" = "unicode", max_chars: int = 20000` | BioC — full text of a PMC Open Access article |
| `export_citation` | `ids: str, db: "pubmed"\|"pmc" = "pubmed", format: "citation"\|"csl"\|"ris"\|"nbib" = "citation"` | Literature Citation Exporter — formatted citation |
| `convert_ids` | `ids: str, idtype: Optional["pmcid"\|"pmid"\|"mid"\|"doi"] = None, versions: bool = False` | PMC ID Converter — convert between PMID/PMCID/MID/DOI |
| `raw_request` | `service: "eutils"\|"bioc"\|"citexport"\|"idconv", path: str, params: Dict[str, Any]` | Raw GET request to any of the four underlying APIs |

## Environment variables

| Variable | Required | Description |
|---------|----------|------|
| `PUBMED_MCP_EMAIL` | no | Email reported to NCBI (recommended by their usage policy) |
| `PUBMED_MCP_API_KEY` | no | NCBI E-utilities API key — raises the rate limit from 3 to 10 requests/second |

## Wiring it up

Only requirement: `uv` (https://docs.astral.sh/uv/). Nothing else to install.

### Claude Code

```
claude mcp add pubmed-mcp -- uvx --from git+https://github.com/dam2452/pubmed-mcp.git pubmed-mcp
```

With optional email/API key:

```
claude mcp add pubmed-mcp -e PUBMED_MCP_EMAIL=<value> -e PUBMED_MCP_API_KEY=<value> -- uvx --from git+https://github.com/dam2452/pubmed-mcp.git pubmed-mcp
```

### Claude Desktop / other MCP client

```json
{
  "mcpServers": {
    "pubmed-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dam2452/pubmed-mcp.git", "pubmed-mcp"],
      "env": { "PUBMED_MCP_EMAIL": "<value>", "PUBMED_MCP_API_KEY": "<value>" }
    }
  }
}
```

After pushing a new version: `uv cache clean` and restart the client.

## Local run

```
uv run --directory . pubmed-mcp
```

Tests (manual):

```
uv run --directory . --with pytest pytest test/
```