# io.github.cyanheads/uniprot-mcp-server (npm · @cyanheads/uniprot-mcp-server)

Protein research over UniProtKB — search by function, fetch curated records, map IDs, proteomes.

- Trust score: 65/100 (medium)
- Change this week: +60
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-07

## Components

- npm · `@cyanheads/uniprot-mcp-server`: 65/100 (this document), [markdown](https://verifymcp.io/servers/cyanheads-uniprot-mcp-server/cyanheads-uniprot-mcp-server.md), [page](https://verifymcp.io/servers/cyanheads-uniprot-mcp-server/cyanheads-uniprot-mcp-server)

## Channel facts

- Registry: `npm`
- Package: `@cyanheads/uniprot-mcp-server`
- Version: `0.2.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-07.

- **Supply Chain Security**: 86/100
  - No malware found by supply-chain analysis.
  - Known CVEs were checked across the 125 of 132 dependencies we could resolve, so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Dependency health was assessed across the 125 of 132 dependencies we could resolve, so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (Apache-2.0).
  - Actively maintained (last published 39 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 76/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 2236 tokens (~372/item across 6 items; 6 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

```bash
claude mcp add cyanheads-uniprot-mcp-server -- npx -y @cyanheads/uniprot-mcp-server
```

### Codex

```bash
codex mcp add cyanheads-uniprot-mcp-server -- npx -y @cyanheads/uniprot-mcp-server
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cyanheads-uniprot-mcp-server": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@cyanheads/uniprot-mcp-server"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add cyanheads-uniprot-mcp-server --command npx --arg -y --arg @cyanheads/uniprot-mcp-server
```

### Hermes

```yaml
mcp_servers:
  cyanheads-uniprot-mcp-server:
    command: "npx"
    args: ["-y", "@cyanheads/uniprot-mcp-server"]
```

### Other

```json
{
  "mcpServers": {
    "cyanheads-uniprot-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/uniprot-mcp-server"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-06 (score 65, +30)

- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] Schema quality: unverified → 100
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Tool coverage: unverified → 100
- [functional] First check of Tool coverage: 100
- [functional] First check of Tool coverage: 100
- [functional] First check of Schema quality: fail
- [functional] First check of Schema quality: excellent
- [functional] First check of Schema quality: fail

### 2026-08-02 (score 35, +30)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] License: unverified → pass
- [functional improvement] Maintenance: unverified → pass
- [functional] Tool coverage: Tool coverage not yet verified: we do not have a sandbox capture of the tool definitions this version of the package serves yet.
- [functional] Schema quality: Schema quality not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional] Capabilities: Protocol version not yet verified: we do not have a sandbox capture of the MCP handshake this version of the package performs yet.
- [functional] Licence: Apache-2.0

### 2026-07-31 (score 5, −19)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 24, 0)

- [functional] Tool coverage: Tool coverage not yet verified: we do not have a sandbox capture of the tool definitions this version of the package serves yet.
- [functional] Schema quality: Schema quality not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.

### 2026-07-27 (score 24)

First indexed and scored.

## MCP tools (6)

### `uniprot_search_proteins` (~534 tokens)

uniprot-mcp-server: search proteins

Search UniProtKB and return curated protein records. Pass text_search for a plain-language query (the 80% case) or query for the full Lucene field syntax (gene:TP53 AND organism_id:9606 AND reviewed:true) — exactly one is required. Reviewed (Swiss-Prot) entries are manually curated; unreviewed (TrEMBL) are computationally predicted and ~30x more numerous, so reviewed defaults to true to avoid drowning in predictions — set it false to include TrEMBL. Request facets (e.g. reviewed, model_organism) for server-side count breakdowns. Results page forward with an opaque cursor; UniProtKB has no offset paging. This is the discovery entry point — chain results[].accession into uniprot_get_entry for full records, or uniprot_get_sequence for FASTA.

Input parameters:

- `cursor` (string): Opaque forward-pagination cursor from a prior response. Walk pages with this; random access to page N is not supported.
- `facets` (string): Comma-separated upstream facet names for count breakdowns, e.g. "reviewed,model_organism,proteins_with". Returns a facets array alongside the hits.
- `fields` (string): Comma-separated UniProtKB field names to project, e.g. "accession,gene_names,cc_function". Omit for a sensible default set covering name, gene, organism, length, reviewed, score, and a function snipp…
- `organism_id` (integer): Restrict to an NCBI taxon ID, e.g. 9606 for human. A convenience filter ANDed onto the query; resolve names with uniprot_get_taxonomy.
- `query` (string): UniProtKB Lucene query with field prefixes — gene, organism_id, keyword (KW-xxxx), go (GO id), reviewed, protein_name, family, length, existence, accession. Example: "gene:BRCA1 AND organism_id:9606…
- `reviewed` (boolean): Restrict to reviewed Swiss-Prot entries. Defaults to true (curated only); set false to include unreviewed TrEMBL. Ignored when query already pins a reviewed: clause.
- `size` (integer): Number of hits per page (max 500). Omit for the server default.
- `text_search` (string): Plain-language search across protein names, gene names, and function, e.g. "kinase apoptosis". Provide this OR query, not both.

Output parameters:

- `cursor` (string): Forward cursor for the next page. Absent on the last page.
- `effectiveQuery` (string): The query as the server assembled and sent it to UniProtKB.
- `facets` (array): Upstream facet count breakdowns. Present only when facets were requested.
- `notice` (string): Guidance when nothing matched — echoes the query and suggests how to broaden.
- `results` (array): Matching protein hits for this page.
- `totalResults` (number): Total matches for the query before pagination (from the upstream result count).

### `uniprot_get_entry` (~320 tokens)

uniprot-mcp-server: get entry

Fetch full curated UniProtKB entries by accession in one batch (up to 20). Each entry carries function, catalytic activity, cofactors, subcellular location, disease involvement, PTMs, natural variants, isoforms, domains, GO terms, keywords, and cross-references. Partial failures do not abort the batch — resolved entries land in succeeded[] and unknown/withdrawn accessions in failed[]. Pass fields to trim the upstream projection. A single oversized record returns kind: "outline" (a section listing with byte sizes) instead of overflowing context — re-call the same accession with sections:[...] (e.g. ["disease","variants"]) to pull only those. This tool does not search: accessions come from uniprot_search_proteins.results[].accession or uniprot_map_ids. Strip any isoform suffix (P04637-2 to P04637) before calling.

Input parameters:

- `accessions` (array, required): Accessions to fetch (1–20). From uniprot_search_proteins or uniprot_map_ids.
- `fields` (string): Comma-separated UniProtKB field names to project, e.g. "accession,gene_names,cc_function,ft_variant". Omit for the full curated default set. Use this on the initial call to trim payload.
- `sections` (array): Only used to re-call after a kind: "outline" response — pass a subset of the outlined section keys to fetch just those sections. Do not pass on the initial call.

Output parameters:

- `failed` (array): Accessions that were well-formed but not found in UniProtKB. Present when kind is "full".
- `kind` (string): Result kind. "full": the batch resolved — read succeeded[] and failed[]. "outline": a single record exceeded the context budget and is returned as a section listing — re-call the same accession with…
- `notice` (string): Re-call guidance when kind is "outline" — re-call the same accession with sections:[...] to pull specific sections.
- `sections` (array): Section outline returned when a single record exceeds the context budget. Present when kind is "outline".
- `succeeded` (array): Entries that resolved successfully. Present when kind is "full".

### `uniprot_map_ids` (~435 tokens)

uniprot-mcp-server: map IDs

Translate identifiers across databases via UniProt's ID-mapping service — gene names to accessions, accession to PDB / Ensembl / RefSeq / ChEMBL / GeneID, and back. The job runs asynchronously; this tool submits it and polls within a budget. If it finishes in time you get status "finished" with the mappings; if it runs long you get status "running" with a ticket — re-call with that ticket (and no other inputs) to fetch the result without re-submitting. A gene name often maps to one reviewed Swiss-Prot accession plus dozens of unreviewed TrEMBL ones, so target UniProtKB-Swiss-Prot (reviewed only) for the usual intent, or UniProtKB / UniProtKB_AC-ID to include TrEMBL. Pair a gene-symbol from_db with tax_id to disambiguate species. Chain the resulting accessions into uniprot_get_entry.

Input parameters:

- `from_db` (string): Source database. Gene_Name = HGNC symbol (pair with tax_id); UniProtKB_AC-ID = accession or entry name; Ensembl/Ensembl_Protein = ENSG/ENSP; PDB; RefSeq_Nucleotide/RefSeq_Protein = NM_/NP_; ChEMBL; G…
- `ids` (array): Identifiers to translate. Required unless resuming with a ticket.
- `tax_id` (integer): NCBI taxon ID to disambiguate ambiguous source IDs (e.g. a gene symbol across species). Recommended with Gene_Name; e.g. 9606 for human.
- `ticket` (string): A ticket from a prior status "running" response. Pass this alone (no from_db/to_db/ids) to fetch the completed result.
- `to_db` (string): Target database. UniProtKB-Swiss-Prot = reviewed accessions only (the usual intent); UniProtKB / UniProtKB_AC-ID also include unreviewed TrEMBL. Required unless resuming with a ticket.

Output parameters:

- `mappedCount` (number): Number of resolved mappings (finished jobs only).
- `notice` (string): Status guidance — e.g. that the job is still running, or that no IDs mapped.
- `results` (array): Resolved mappings (present when status is "finished"). A source ID with no mapping is simply absent.
- `status` (string): Job state: "finished" (results included) or "running" (re-call with the ticket).
- `ticket` (string): Resumable job ticket (present when status is "running"). Re-call this tool with ticket set, and nothing else, to fetch the result.
- `unmappedIds` (array): Input IDs with no mapping in the target database (finished jobs only). Absent when resuming or all mapped.

### `uniprot_get_proteome` (~355 tokens)

uniprot-mcp-server: get proteome

Fetch the reference proteome for an organism by UPID (e.g. "UP000005640") or NCBI taxon ID (e.g. 9606) — provide exactly one. Returns metadata inline: proteome type, total protein count, BUSCO completeness (score, complete/fragmented/missing counts, lineage dataset), and the 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; narrow it with the query filter (UniProtKB Lucene syntax) for a subset. Resolve an organism name to a taxon ID first with uniprot_get_taxonomy.

Input parameters:

- `cursor` (string): Forward-pagination cursor from a prior protein page. Only meaningful with include_proteins.
- `include_proteins` (boolean): When true, also return a capped, cursor-paginated page of the proteome's proteins. Defaults to false — metadata alone is the common case.
- `query` (string): Optional UniProtKB Lucene filter to narrow the protein list, e.g. "reviewed:true AND keyword:KW-0067". Only applies when include_proteins is true.
- `size` (integer): Proteins per page when include_proteins is true (max 500). Omit for the server default.
- `taxon_id` (integer): NCBI taxon ID, e.g. 9606 for human. Resolves to the reference proteome. Provide this OR upid, not both.
- `upid`: Proteome UPID. Provide this OR taxon_id, not both.

Output parameters:

- `cap` (number): The page-size cap that was applied.
- `cursor` (string): Forward cursor for the next protein page. Absent on the last page.
- `notice` (string): Truncation guidance when the protein page was capped — how to reach the rest (walk the cursor or narrow with the query filter).
- `proteins` (array): A capped page of the proteome's proteins. Present only when include_proteins is true.
- `proteome` (object): Proteome metadata.
- `shown` (number): Number of proteins returned in this page.
- `totalProteinsMatched` (number): Total proteins matching the (optionally filtered) proteome query.
- `truncated` (boolean): True when the protein page hit the size cap — more remain via cursor.

### `uniprot_get_taxonomy` (~219 tokens)

uniprot-mcp-server: get taxonomy

Resolve a taxonomy record by NCBI taxon ID (e.g. 9606) or scientific name (e.g. "Homo sapiens") — provide exactly one. Returns the scientific and common name, mnemonic, rank, parent, and the full lineage. Set include_children to also fetch immediate child taxa (a separate lookup — not inline on the record). Use this to turn an organism name into the taxon ID that uniprot_search_proteins (organism_id) and uniprot_get_proteome (taxon_id) expect.

Input parameters:

- `include_children` (boolean): When true, also fetch the immediate child taxa via a follow-up search. Defaults to false.
- `name` (string): Organism scientific name, e.g. "Homo sapiens". Provide this OR taxon_id, not both. Matched against the scientific name.
- `taxon_id` (integer): NCBI taxonomy ID, e.g. 9606. Provide this OR name, not both.

Output parameters:

- `childCount` (number): Number of immediate children returned (when include_children is true).
- `children` (array): Immediate children. Present only when include_children is true.
- `lineage` (array): Full lineage from root to the taxon's near ancestor.
- `taxon` (object): The taxonomy record.

### `uniprot_get_sequence` (~170 tokens)

uniprot-mcp-server: get sequence

Fetch the canonical amino-acid sequence (FASTA) for a UniProtKB accession, with length and the parsed header. Set include_isoforms to also return the alternatively-spliced isoform sequences. This is the cheap sequence-only path — for the full functional record use uniprot_get_entry. Accessions come from uniprot_search_proteins or uniprot_map_ids; strip any "-N" isoform suffix (P04637-2 to P04637) before calling.

Input parameters:

- `accession` (string, required): UniProtKB primary accession, e.g. "P04637". Canonical form only — strip any "-N" isoform suffix.
- `include_isoforms` (boolean): When true, also return the isoform sequences. Defaults to false (canonical only).

Output parameters:

- `accession` (string): The accession that was fetched.
- `canonical` (object): The canonical sequence record.
- `isoforms` (array): Isoform sequence records. Present only when include_isoforms is true and isoforms exist.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/cyanheads-uniprot-mcp-server/cyanheads-uniprot-mcp-server#diagnostics

## Score history

- 2026-08-07: 65
- 2026-08-06: 65
- 2026-08-05: 35
- 2026-08-04: 35
- 2026-08-03: 35
- 2026-08-02: 35
- 2026-08-01: 5
- 2026-07-31: 5
- 2026-07-30: 24
- 2026-07-28: 24
- 2026-07-27: 24

## Links

- npm package: https://www.npmjs.com/package/@cyanheads/uniprot-mcp-server
- Socket report: https://socket.dev/npm/package/@cyanheads/uniprot-mcp-server
- Repository: https://github.com/cyanheads/uniprot-mcp-server
- Changelog RSS feed: https://verifymcp.io/servers/cyanheads-uniprot-mcp-server/cyanheads-uniprot-mcp-server.xml
- Changelog JSON feed: https://verifymcp.io/servers/cyanheads-uniprot-mcp-server/cyanheads-uniprot-mcp-server.json
- HTML version of this page: https://verifymcp.io/servers/cyanheads-uniprot-mcp-server/cyanheads-uniprot-mcp-server