uniprot-mcp

<!-- mcp-name: io.github.smaniches/uniprot-mcp -->

# UniProt MCP Server

[![CI](https://github.com/smaniches/uniprot-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/smaniches/uniprot-mcp/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![MCP compatible](https://img.shields.io/badge/MCP-compatible-6e56cf.svg)](https://modelcontextprotocol.io/)
[![Tests](https://img.shields.io/badge/tests-874_offline_%2B_44_live-success)](#testing)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](pyproject.toml)
[![Provenance: SHA-256 + verify](https://img.shields.io/badge/provenance-SHA--256_+_verify-blue)](#provenance--verification)
[![ORCID](https://img.shields.io/badge/ORCID-0009--0005--6480--1987-A6CE39?logo=orcid&logoColor=white)](https://orcid.org/0009-0005-6480-1987)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19817710-3C5A99?logo=zenodo&logoColor=white)](https://doi.org/10.5281/zenodo.19817710)

UniProt MCP server — a **Model Context Protocol** server for the
[UniProt](https://www.uniprot.org) protein knowledgebase with
**per-query provenance verification**. **41 tools** across 8
families. Apache-2.0. Every successful response carries a verifiable
`Provenance` record — UniProt release, retrieval timestamp, resolved
URL, and a SHA-256 of the canonical response body — that the agent
(or a third party, a year later) can re-check with a single tool
call: `uniprot_provenance_verify`.

The distinguishing capability: **per-response SHA-256 + verify primitive
+ release pinning + offline replay** is, to the best of my survey of
public MCPs as of 2026-04-26, absent from every other bio-MCP server I
could find
(BioMCP, Augmented-Nature/UniProt-MCP, biothings-mcp, gget-mcp, and
others). If you are a regulated-bio-pharma user who needs to prove,
years later, that a UniProt-derived claim still holds, this is the
mechanism. Comparison and citations: [docs/COMPETITIVE_LANDSCAPE.md](docs/COMPETITIVE_LANDSCAPE.md).

> Author: **Santiago Maniches** · ORCID [0009-0005-6480-1987](https://orcid.org/0009-0005-6480-1987) · TOPOLOGICA LLC

**Run it in one line:**

```bash
uvx uniprot-mcp-server
```

---

## Verifiable provenance (the receipts)

Every answer this server returns is traceable to a primary-source URL **and**
a content hash you can re-compute yourself. The walkthrough below is a real
run against the live server (UniProt release `2026_01`), independently
confirmed against the UniProt REST API.

**Question.** What is the function of human p53 (UniProt `P04637`), what
heritable cancer syndrome is it associated with, and is the `R175H` mutation
a documented disease variant?

**Answer, with its provenance footer (verbatim from the server):**

- **Function.** *Cellular tumor antigen p53* (gene `TP53`, *Homo sapiens*,
  393 aa). "Multifunctional transcription factor that induces cell cycle
  arrest, DNA repair or apoptosis... Acts as a tumor suppressor in many tumor
  types."
- **Disease.** *Li-Fraumeni syndrome* (acronym `LFS`, UniProt disease id
  `DI-01904`, OMIM `151623`) — "an autosomal dominant familial cancer
  syndrome... Four types of cancers account for 80% of tumors occurring in
  TP53 germline mutation carriers."
- **Variant.** `R175H` — "in LFS; germline mutation and in sporadic cancers;
  somatic mutation; does not induce SNAI1 degradation; reduces interaction
  with ZNF385A; dbSNP:`rs28934578`."

```
Source: UniProt release 2026_01 (28-January-2026) • Retrieved 2026-06-09T11:47:51Z
Query: https://rest.uniprot.org/uniprotkb/P04637
SHA-256: 0040d79bb39e2f7386d55f81071e87858ec2e5c2cd9552e93c3633897f78345e
Accept: application/json
```

### Reproduce it

**1. Run the server and ask the same question** (any MCP client; tool calls shown):

```bash
uvx uniprot-mcp-server
# uniprot_get_entry(accession="P04637")               -> function + gene + diseases
# uniprot_get_disease_associations(accession="P04637") -> LFS, OMIM 151623
# uniprot_lookup_variant(accession="P04637", change="R175H") -> the LFS variant record
```

**2. Confirm the hash re-verifies** (re-fetches the URL and re-checks the
release + canonical hash with the server's own code):

```bash
# uniprot_provenance_verify(
#   url="https://rest.uniprot.org/uniprotkb/P04637",
#   release="2026_01",
#   response_sha256="0040d79bb39e2f7386d55f81071e87858ec2e5c2cd9552e93c3633897f78345e")
# -> Status: verified  (release match + SHA-256 match)
```

**3. Confirm the values against the primary source — no server in the loop:**

```bash
curl -s -H "Accept: application/json" https://rest.uniprot.org/uniprotkb/P04637 -o p53.json

# UniProt release served (matches the footer):
curl -sI -H "Accept: application/json" https://rest.uniprot.org/uniprotkb/P04637 | grep -i x-uniprot-release
# -> X-UniProt-Release: 2026_01

python - <<'PY'
import json, hashlib
d = json.load(open("p53.json", encoding="utf-8"))
print("gene        :", d["genes"][0]["geneName"]["value"])                       # TP53
print("protein     :", d["proteinDescription"]["recommendedName"]["fullName"]["value"])  # Cellular tumor antigen p53
print("organism    :", d["organism"]["scientificName"], "| length", d["sequence"]["length"])  # Homo sapiens | 393
for c in d["comments"]:
    if c.get("commentType") == "DISEASE" and c["disease"].get("acronym") == "LFS":
        x = c["disease"]
        print("disease     :", x["diseaseId"], "| OMIM", x["diseaseCrossReference"]["id"])  # Li-Fraumeni syndrome | 151623
for f in d["features"]:
    if f.get("type") == "Natural variant" and f["location"]["start"]["value"] == 175:
        a = f.get("alternativeSequence", {})
        if a.get("originalSequence") == "R" and a.get("alternativeSequences") == ["H"]:
            print("variant     : R175H |", f["description"])  # in LFS; germline mutation ...

# The footer SHA-256 is reproducible from these exact bytes (no server):
# the server hashes the JSON re-serialized with sorted keys + compact separators.
canonical = json.dumps(d, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
print("sha-256     :", hashlib.sha256(canonical).hexdigest())
# -> 0040d79bb39e2f7386d55f81071e87858ec2e5c2cd9552e93c3633897f78345e
PY
```

**What this proves:** every returned claim is traceable to a primary-source
URL and a content hash. The gene, protein name, disease (with OMIM id), and
variant the server reports all match the live UniProt entry; the footer
SHA-256 is reproducible byte-for-byte from the primary source using a
documented, server-independent recipe. A third party can re-run all three
checks today, or a year from now, without trusting this server.

> Note on the hash: the footer SHA-256 is of the *canonical* UniProt response
> body — the JSON re-serialized with sorted keys and compact separators
> (`json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)`),
> so harmless key-order changes within a release do not break verification. A raw
> `curl | sha256sum` of the bytes will therefore differ; apply the same
> canonicalization (step 3 above) or use `uniprot_provenance_verify`.

---

## Installation

Run without installing (recommended):

```bash
uvx uniprot-mcp-server
```

Or install into an environment:

```bash
pip install uniprot-mcp-server
```


> **Note:** There is an unrelated package named `uniprot-mcp` on PyPI
> (different author, 5 tools, MIT). This package is `uniprot-mcp-server`.
> Running `pip install uniprot-mcp` will install the wrong package silently.

## For researchers — where to start

If you are a biomedical researcher visiting this repo, the highest-signal places to look are:

| Resource | What it gives you |
|---|---|
| **[`examples/atlas/`](examples/atlas/)** | Two artifacts with deliberately different scopes: <br>• **Curated atlas (25 entries).** TP53, BRCA1, CFTR, HTT, EGFR, BRAF, KRAS, TEM-1 β-lactamase, more — each linking the canonical UniProt accession to MONDO / OMIM / PharmGKB / ARO IDs and the relevant tool sequence. JSON-LD manifest at `examples/atlas/atlas.json`. <br>• **Comprehensive index (11,590 rows).** UniProt's curated disease + pathogen surface as two TSVs (`comprehensive_index.tsv` 7,250 human disease rows, `comprehensive_index_pathogens.tsv` 4,340 pathogen rows). Each row carries a UniProt disease ID and an OMIM cross-reference where available. MONDO / PharmGKB / ARO mappings exist only in the 25-entry curated atlas, not in the 11,590-row index. SHA-256 reproducibility manifest at `examples/atlas/manifest.json`. <br>Methodology (how compiled, what's verified, what's community-reviewable) at `examples/atlas/METHODOLOGY.md`. |
| **[`examples/01..04.jsonl`](examples/)** | Full Claude-Desktop transcripts of clinical-variant interpretation (TP53 R175H), drug-target dossier (BRCA1), provenance verification a year later, pathogen drug-discovery (TEM-1). |
| **[`tests/benchmark/`](tests/benchmark/)** | Pre-registered 30-prompt benchmark with SHA-256 commitments on `main`. The 2026-04-26 v1.1.0 run verified 30/30 against live UniProt — transcript at `tests/benchmark/run-2026-04-26-v1.1.0/`. |
| **[`scripts/replicate.sh`](scripts/replicate.sh)** | One-command verification that the published PyPI wheel was built from this exact repo (cross-checks SHA-256 across PyPI / GitHub Release / SLSA attestation; runs `--self-test`; re-runs the benchmark live). POSIX + `scripts/replicate.ps1` for Windows. |
| **[`docs/COMPETITIVE_LANDSCAPE.md`](docs/COMPETITIVE_LANDSCAPE.md)** | Honest 14-server survey of the bio-MCP space (April 2026) and the specific differentiation this server claims. |

Issues / corrections welcome at https://github.com/smaniches/uniprot-mcp/issues. The atlas in particular is community-reviewable — see METHODOLOGY.md for what is machine-verified vs what needs human review.

---

## What makes this different

| | uniprot-mcp | Vanilla LLM + We