uniprot-mcp-server

<div align="center">
  <h1>@cyanheads/uniprot-mcp-server</h1>
  <p><b>Search UniProtKB by protein function, fetch curated records, map IDs across databases, and pull reference proteomes, taxonomy, and sequences via MCP. STDIO or Streamable HTTP.</b>
  <div>6 Tools • 2 Resources • 1 Prompt</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.2.6-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/uniprot-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/uniprot-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/uniprot-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.3-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/uniprot-mcp-server/releases/latest/download/uniprot-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=uniprot-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvdW5pcHJvdC1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22uniprot-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Funiprot-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://uniprot.caseyjhand.com/mcp](https://uniprot.caseyjhand.com/mcp)

</div>

---

## Overview

Protein research over UniProtKB (rest.uniprot.org). Search by function or gene, fetch curated records, translate identifiers across sibling databases, and pull reference proteomes, taxonomy, and sequences from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

### Tools

| Tool | Description |
|:---|:---|
| `uniprot_search_proteins` | Search UniProtKB by plain text or a Lucene field query, with the reviewed (Swiss-Prot) filter foregrounded and optional server-side facet counts. Cursor-paginated. The discovery entry point. |
| `uniprot_get_entry` | Fetch full curated entries by accession in one batch (up to 20) — function, catalytic activity, disease, variants, isoforms, GO terms, cross-references. Partial-success output; an oversized record returns a section outline. |
| `uniprot_map_ids` | Translate identifiers across databases via UniProt's async ID-mapping service — gene names, Ensembl, RefSeq, ChEMBL, PDB, GeneID ↔ UniProtKB accessions. Polls within a budget; running jobs return a ticket and completed pages return a continuation. |
| `uniprot_get_proteome` | Fetch a reference proteome by UPID or NCBI taxon ID — protein count, BUSCO completeness, genome assembly inline, plus an opt-in capped page of the proteins. |
| `uniprot_get_taxonomy` | Resolve a taxonomy record by NCBI taxon ID or scientific name — name, rank, parent, full lineage, and optionally the immediate children, cursor-paginated. |
| `uniprot_get_sequence` | Fetch the canonical amino-acid sequence (FASTA) for an accession, with length and parsed header — and optionally the isoform sequences. The cheap sequence-only path. |

### Resources

| Resource | Description |
|:---|:---|
| `uniprot://entry/{accession}` | A curated UniProtKB entry by accession — the resource mirror of `uniprot_get_entry` for a single accession. |
| `uniprot://taxonomy/{taxonId}` | A taxonomy record by NCBI taxon ID — name, rank, parent, full lineage. The mirror of `uniprot_get_taxonomy` by ID. |

All resource data is also reachable via tools — tool-only clients lose nothing. UniProtKB is far too large to enumerate, so there is no resource `list()`; discovery is `uniprot_search_proteins`'s job.

### Prompts

| Prompt | Description |
|:---|:---|
| `uniprot_protein_dossier` | Guided protein-research workflow — resolve an identifier, fetch the curated entry, pull disease and variants, and surface cross-references for structure, citations, and bioactivity. |

## Capability reference

### `uniprot_search_proteins` <sub>tool</sub>

- `text_search` for plain language (the 80% case) **or** `query` for full Lucene field syntax (`gene`, `organism_id`, `keyword`, `go`, `reviewed`, `protein_name`, `family`, `length`, `existence`, `accession`) — exactly one
- `reviewed` defaults to `true` (Swiss-Prot only) so the agent isn't drowned in TrEMBL predictions; `false` searches both tiers together (put `reviewed:false` in `query` for TrEMBL only)
- `organism_id` convenience filter ANDed onto the whole query — the caller's clause is parenthesized first, so a top-level `OR` stays filtered on every branch; a clause with unbalanced parentheses is rejected before the request
- Optional `facets` for server-side count breakdowns (e.g. `reviewed`, `model_organism`)
- Forward cursor pagination (UniProtKB has no offset paging); `totalResults` and the effective query echoed back. A cursor UniProt can't continue from fails `invalid_cursor`: restart without it
- Every hit carries `reviewed`, `annotationScore`, and `proteinExistence` so curation quality is weighable
- An inactive accession the query matches (merged, demerged, or deleted) lands in `inactive[]` with its reason and replacement accessions or UniParc ID — never in `results[]` as a hollow hit

---

### `uniprot_get_entry` <sub>tool</sub>

- Batch up to 20 accessions in one round trip
- Sectioned record: function, catalytic activity, cofactors, subcellular location, disease, PTMs, natural variants, isoforms, domains, GO terms, keywords, cross-references
- Partial-success output — resolved entries in `succeeded[]`, unknown or inactive ones in `failed[]`; the whole batch never aborts on one bad accession
- An inactive accession (merged, demerged, or deleted) is reported in `failed[]`, never as a record — its error names the merge target to retry with, the demerge products, or the UniParc ID that keeps a deleted sequence
- `fields` trims the upstream projection; identity and provenance fields are always retained
- A single oversized record returns `kind: "outline"` (a section listing) instead of overflowing context — re-call the same accession with `sections: [...]` to pull only what's needed (one accession per `sections` call; trim a batch with `fields`)
- A list section too large on its own (p53's natural variants, over a thousand) pages with `section_limit` (1–500) and `section_offset` on a re-call naming that one section; each window reports `totalCount` and, while items remain, `nextOffset`
- Accessions come from `uniprot_search_proteins` or `uniprot_map_ids`; strip any `-N` isoform suffix first

---

### `uniprot_map_ids` <sub>tool</sub>

- `from_db` / `to_db` are validated enums (e.g. `Gene_Name`, `Ensembl`, `RefSeq_Protein`, `ChEMBL`, `PDB`, `GeneID`, and `UniProtKB_AC-ID` as a source) so an unknown database fails before the upstream call
- Target `UniProtKB-Swiss-Prot` for reviewed accessions only (the usual intent), or `UniProtKB` to include unreviewed TrEMBL
- The job runs asynchronously; the tool submits it and polls within a budget. A running job returns `status: "running"` with a ticket — pass that ticket alone to poll the same job
- A completed call returns `status: "finished"` with one upstream page. If `continuation` is present, pass it alone to fetch the next completed page without polling or re-submitting; its absence marks the terminal page
- Pair a gene-symbol `from_db` with `tax_id` to disambiguate species
- `unmappedIds` is populated only from UniProt's `failedIds`, so identifiers UniProt normalizes in successful result rows are not misclassified as failures
- A row whose UniProtKB target is inactive (merged, demerged, or deleted) stays a mapping but carries an `inactive` marker with the reason and replacements; active targets carry none

---

### `uniprot_get_proteome` <sub>tool</sub>

- Provide exactly one of `upid` (e.g. `UP000005640`) or `taxon_id` — providing both or neither fails validation
- Metadata inline: proteome type, total protein count, BUSCO completeness (score, complete/fragmented/missing counts, lineage dataset), genome assembly accession
- The protein set is opt-in via `include_proteins` (it is large — human is ~147,506) and returns a capped page with a forward cursor and truncation disclosure; a cursor UniProt can't continue from fails `invalid_cursor`
- Narrow the protein list with the `query` filter (UniProtKB Lucene syntax) for a subset
- Resolve an organism name to a taxon ID first with `uniprot_get_taxonomy`

---

### `uniprot_get_taxonomy` <sub>tool</sub>

- Provide exactly one of `taxon_id` (NCBI numeric ID) or `name` (scientific name) — both or neither fails validation
- Returns scientific and common name, mnemonic, rank, parent, and the full lineage (root → near ancestor)
- `include_children` fetches the immediate child taxa via a follow-up search (not inline on the record), 100 per page with the total child count; when more remain, the response carries truncation disclosure and a `cursor` for the next page. The cursor names its taxon, so one sent with another taxon fails `invalid_