io.github.cyanheads/uniprot-mcp-server

Official6 toolsLive

by cyanheads · TypeScript

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

@cyanheads/uniprot-mcp-server (MCP Server)

Protein research over UniProtKB, providing MCP access to search by protein function, fetch curated UniProt records, map IDs across databases, and retrieve reference proteomes, taxonomy, and sequences. The server is designed to run via STDIO or Streamable HTTP.

🛠️ Key Features

Search UniProtKB by protein function
Fetch curated UniProt records
Map IDs across databases
Pull reference proteomes, taxonomy, and sequences
Provides 6 MCP tools

🚀 Use Cases

Curate and retrieve protein records from UniProtKB
Convert or align protein identifiers across databases
Acquire reference proteomes with associated taxonomy
Download sequences for downstream bioinformatics workflows

⚡ Developer Benefits

MCP integration for UniProtKB-centered protein research
Two transport options: STDIO and Streamable HTTP
Topic alignment with bioinformatics and proteomics workflows

⚠️ Limitations

Server description does not specify additional constraints beyond UniProtKB scope
Details of the 6 tools and 2 resources are not included in the provided excerpt

Topics

bioinformaticscyanheadsmcpmodel-context-protocolproteinproteomeproteomicsswiss-prottypescriptuniprotuniprotkb

Captured live from the server via tools/list.

uniprot_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.

Parameters8

text_search	string	optional	Plain-language search across protein names, gene names, and function, e.g. "kinase apoptosis". Provide this OR query, not both.
query	string	optional	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 AND reviewed:true". Provide this OR text_search, not both.
reviewed	boolean	optional	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.
organism_id	integer	optional	Restrict to an NCBI taxon ID, e.g. 9606 for human. A convenience filter ANDed onto the query; resolve names with uniprot_get_taxonomy.
fields	string	optional	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 snippet.
facets	string	optional	Comma-separated upstream facet names for count breakdowns, e.g. "reviewed,model_organism,proteins_with". Returns a facets array alongside the hits.
size	integer	optional	Number of hits per page (max 500). Omit for the server default.
cursor	string	optional	Opaque forward-pagination cursor from a prior response. Walk pages with this; random access to page N is not supported.

Raw schema

{
  "type": "object",
  "properties": {
    "text_search": {
      "description": "Plain-language search across protein names, gene names, and function, e.g. \"kinase apoptosis\". Provide this OR query, not both.",
      "type": "string"
    },
    "query": {
      "description": "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 AND reviewed:true\". Provide this OR text_search, not both.",
      "type": "string"
    },
    "reviewed": {
      "default": true,
      "description": "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.",
      "type": "boolean"
    },
    "organism_id": {
      "description": "Restrict to an NCBI taxon ID, e.g. 9606 for human. A convenience filter ANDed onto the query; resolve names with uniprot_get_taxonomy.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "fields": {
      "description": "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 snippet.",
      "type": "string"
    },
    "facets": {
      "description": "Comma-separated upstream facet names for count breakdowns, e.g. \"reviewed,model_organism,proteins_with\". Returns a facets array alongside the hits.",
      "type": "string"
    },
    "size": {
      "description": "Number of hits per page (max 500). Omit for the server default.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 500
    },
    "cursor": {
      "description": "Opaque forward-pagination cursor from a prior response. Walk pages with this; random access to page N is not supported.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

uniprot_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.

Parameters3

accessions	array	required	Accessions to fetch (1–20). From uniprot_search_proteins or uniprot_map_ids.
fields	string	optional	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	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "accessions": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^(?:[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9](?:[A-Z][A-Z0-9]{2}[0-9]){1,2})$",
        "description": "A UniProtKB primary accession, e.g. \"P04637\". Canonical form only — strip any \"-N\" isoform suffix."
      },
      "description": "Accessions to fetch (1–20). From uniprot_search_proteins or uniprot_map_ids."
    },
    "fields": {
      "description": "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.",
      "type": "string"
    },
    "sections": {
      "description": "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.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "A section key from a prior outline response, e.g. \"disease\", \"variants\", \"function\", \"xrefs\"."
      }
    }
  },
  "required": [
    "accessions"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

uniprot_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. 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 results page; when continuation is present, pass it alone to fetch the next completed page without re-submitting or polling the job. 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.

Parameters6

from_db	string	optional	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; GeneID = NCBI Gene. Required only when submitting a new mapping job; omitted when resuming with a ticket or continuation.
to_db	string	optional	Target database. UniProtKB-Swiss-Prot = reviewed accessions only (the usual intent); UniProtKB / UniProtKB_AC-ID also include unreviewed TrEMBL. Required only when submitting a new mapping job; omitted when resuming with a ticket or continuation.
ids	array	optional	Identifiers to translate. Required only when submitting a new mapping job; omitted when resuming with a ticket or continuation.
tax_id	integer	optional	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	optional	Running-job ticket from a prior status "running" response. Pass it alone to poll that job; do not combine it with continuation or submission inputs.
continuation	object	optional	Completed-page continuation from a prior status "finished" response. Pass it alone to fetch the next page without polling or re-submitting.

Raw schema

{
  "type": "object",
  "properties": {
    "from_db": {
      "description": "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; GeneID = NCBI Gene. Required only when submitting a new mapping job; omitted when resuming with a ticket or continuation.",
      "type": "string",
      "enum": [
        "UniProtKB_AC-ID",
        "Gene_Name",
        "GeneID",
        "Ensembl",
        "Ensembl_Protein",
        "PDB",
        "RefSeq_Nucleotide",
        "RefSeq_Protein",
        "ChEMBL",
        "PomBase",
        "WormBase_Protein"
      ]
    },
    "to_db": {
      "description": "Target database. UniProtKB-Swiss-Prot = reviewed accessions only (the usual intent); UniProtKB / UniProtKB_AC-ID also include unreviewed TrEMBL. Required only when submitting a new mapping job; omitted when resuming with a ticket or continuation.",
      "type": "string",
      "enum": [
        "UniProtKB",
        "UniProtKB-Swiss-Prot",
        "UniProtKB_AC-ID",
        "Gene_Name",
        "GeneID",
        "Ensembl",
        "Ensembl_Protein",
        "PDB",
        "RefSeq_Nucleotide",
        "RefSeq_Protein",
        "ChEMBL",
        "PomBase",
        "WormBase_Protein"
      ]
    },
    "ids": {
      "description": "Identifiers to translate. Required only when submitting a new mapping job; omitted when resuming with a ticket or continuation.",
      "maxItems": 100000,
      "type": "array",
      "items": {
        "type": "string",
        "description": "A source identifier in the from_db namespace, e.g. \"TP53\" for Gene_Name."
      }
    },
    "tax_id": {
      "description": "NCBI taxon ID to disambiguate ambiguous source IDs (e.g. a gene symbol across species). Recommended with Gene_Name; e.g. 9606 for human.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "ticket": {
      "description": "Running-job ticket from a prior status \"running\" response. Pass it alone to poll that job; do not combine it with continuation or submission inputs.",
      "type": "string",
      "minLength": 1
    },
    "continuation": {
      "description": "Completed-page continuation from a prior status \"finished\" response. Pass it alone to fetch the next page without polling or re-submitting.",
      "type": "object",
      "properties": {
        "jobId": {
          "type": "string",
          "minLength": 1,
          "description": "UniProt ID-mapping job identifier for the completed job."
        },
        "cursor": {
          "type": "string",
          "minLength": 1,
          "description": "Opaque cursor for the next completed results page."
        }
      },
      "required": [
        "jobId",
        "cursor"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

uniprot_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.

Parameters6

upid	any	optional	Proteome UPID. Provide this OR taxon_id, not both.
taxon_id	integer	optional	NCBI taxon ID, e.g. 9606 for human. Resolves to the reference proteome. Provide this OR upid, not both.
include_proteins	boolean	optional	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	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	optional	Proteins per page when include_proteins is true (max 500). Omit for the server default.
cursor	string	optional	Forward-pagination cursor from a prior protein page. Only meaningful with include_proteins.

Raw schema

{
  "type": "object",
  "properties": {
    "upid": {
      "description": "Proteome UPID. Provide this OR taxon_id, not both.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^UP[0-9]{9}$",
          "description": "Proteome identifier, e.g. \"UP000005640\"."
        }
      ]
    },
    "taxon_id": {
      "description": "NCBI taxon ID, e.g. 9606 for human. Resolves to the reference proteome. Provide this OR upid, not both.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "include_proteins": {
      "default": false,
      "description": "When true, also return a capped, cursor-paginated page of the proteome's proteins. Defaults to false — metadata alone is the common case.",
      "type": "boolean"
    },
    "query": {
      "description": "Optional UniProtKB Lucene filter to narrow the protein list, e.g. \"reviewed:true AND keyword:KW-0067\". Only applies when include_proteins is true.",
      "type": "string"
    },
    "size": {
      "description": "Proteins per page when include_proteins is true (max 500). Omit for the server default.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 500
    },
    "cursor": {
      "description": "Forward-pagination cursor from a prior protein page. Only meaningful with include_proteins.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

uniprot_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.

Parameters3

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

Raw schema

{
  "type": "object",
  "properties": {
    "taxon_id": {
      "description": "NCBI taxonomy ID, e.g. 9606. Provide this OR name, not both.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "name": {
      "description": "Organism scientific name, e.g. \"Homo sapiens\". Provide this OR taxon_id, not both. Matched against the scientific name.",
      "type": "string"
    },
    "include_children": {
      "default": false,
      "description": "When true, also fetch the immediate child taxa via a follow-up search. Defaults to false.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

uniprot_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.

Parameters2

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

Raw schema

{
  "type": "object",
  "properties": {
    "accession": {
      "type": "string",
      "pattern": "^(?:[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9](?:[A-Z][A-Z0-9]{2}[0-9]){1,2})$",
      "description": "UniProtKB primary accession, e.g. \"P04637\". Canonical form only — strip any \"-N\" isoform suffix."
    },
    "include_isoforms": {
      "default": false,
      "description": "When true, also return the isoform sequences. Defaults to false (canonical only).",
      "type": "boolean"
    }
  },
  "required": [
    "accession"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md18 KBView on GitHub

@cyanheads/uniprot-mcp-server

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.

6 Tools • 2 Resources • 1 Prompt

Version MCP SDK TypeScript

Public Hosted Server: https://uniprot.caseyjhand.com/mcp

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.
`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` _tool

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; set false to include them
organism_id convenience filter ANDed onto the query
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
Every hit carries reviewed, annotationScore, and proteinExistence so curation quality is weighable

`uniprot_get_entry` _tool

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/withdrawn ones in failed[]; the whole batch never aborts on one bad accession
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
Accessions come from uniprot_search_proteins or uniprot_map_ids; strip any -N isoform suffix first

`uniprot_map_ids` _tool

from_db / to_db are validated enums (e.g. Gene_Name, Ensembl, RefSeq_Protein, ChEMBL, PDB, GeneID, UniProtKB_AC-ID) so an unsupported pair fails before the upstream call
Target UniProtKB-Swiss-Prot for reviewed accessions only (the usual intent), or UniProtKB / UniProtKB_AC-ID 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

`uniprot_get_proteome` _tool

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
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` _tool

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)
Turns an organism name into the taxon ID that uniprot_search_proteins (organism_id) and uniprot_get_proteome (taxon_id) expect

`uniprot_get_sequence` _tool

Returns the canonical sequence with its length and parsed FASTA header
include_isoforms also returns the alternatively-spliced isoform sequences
Accessions come from uniprot_search_proteins or uniprot_map_ids; strip any -N isoform suffix first

`uniprot://entry/{accession}` _resource

Same record as uniprot_get_entry for a single accession, addressed by URI instead of a tool call
An annotation-heavy entry over the outline budget returns a bounded identity summary plus a section outline instead of the full record — fetch specific sections via the uniprot_get_entry tool (sections: [...]); the resource URI itself takes no sections parameter
The overflow summary always keeps identity fields — accession, entry name, protein name, genes, organism, length, reviewed status, annotation score, protein existence

`uniprot://taxonomy/{taxonId}` _resource

Addressed by NCBI taxon ID, e.g. uniprot://taxonomy/9606 for human
Returns scientific and common name, mnemonic, rank, parent, and full lineage — same shape as uniprot_get_taxonomy without include_children
Tool-only clients reach the same data via uniprot_get_taxonomy

`uniprot_protein_dossier` _prompt

Arguments: identifier required (gene name, accession, or protein name); organism optional to disambiguate
Five-step workflow embedded in the generated message: resolve identifier → fetch entry → summarize function/localization/provenance → pull disease & variants → surface cross-references for structure (PDB), bioactivity (ChEMBL), and citations (PubMed)
Returns a single user-role message carrying the full instructions — no separate assistant framing message

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

UniProt-specific:

Keyless — UniProt REST requires no API key; works against any rest.uniprot.org-compatible base (override UNIPROT_BASE_URL for a private mirror)
One thin fetch client over all four REST collections (UniProtKB, ID Mapping, Proteomes, Taxonomy) with retry/backoff and HTML-error-page detection
Batch entry fetch — N accessions in one round trip, cross-referenced against the request to flag any missing
Async ID-mapping run → poll bounded by a wall-clock budget, with a running-job ticket and separately paginated completed results

Agent-friendly output:

Provenance is data, not decoration — reviewed, annotationScore, proteinExistence, and per-field PubMed/ECO evidence ship on every record so the agent can weigh manual vs. predicted annotation
Graceful partial failure — uniprot_get_entry returns per-accession succeeded[] / failed[] rows instead of aborting the batch
Discriminated output contracts — uniprot_get_entry returns kind: "full" | "outline", while uniprot_map_ids separates a running-job ticket from a finished-page continuation; callers branch on data, not string parsing
Sparsity preserved — absent upstream fields stay absent, never fabricated (most curated sections are legitimately missing on TrEMBL entries)

Getting started

Public Hosted Instance

A public instance is available at https://uniprot.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "uniprot-mcp-server": {
      "type": "streamable-http",
      "url": "https://uniprot.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file. UniProt REST is keyless — no API key required.

json

{
  "mcpServers": {
    "uniprot-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/uniprot-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "uniprot-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/uniprot-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "uniprot-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/uniprot-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.3.0 or higher (or Node.js v24+).
No API key — UniProt REST is keyless and open. Data is UniProt, CC BY 4.0.

Installation

Clone the repository:

git clone https://github.com/cyanheads/uniprot-mcp-server.git

Navigate into the directory:

cd uniprot-mcp-server

Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. UniProt REST is keyless, so every server-specific variable below is an optional override.

Variable	Description	Default
`UNIPROT_BASE_URL`	UniProt REST base URL. Override for a private mirror or testing.	`https://rest.uniprot.org`
`UNIPROT_TIMEOUT_MS`	Per-request HTTP timeout in ms.	`30000`
`UNIPROT_ID_MAPPING_BUDGET_MS`	Wall-clock budget for the inline ID-mapping poll loop before returning a resumable ticket. Must be less than `UNIPROT_TIMEOUT_MS`.	`8000`
`UNIPROT_DEFAULT_PAGE_SIZE`	Default page size for search and proteome protein listing when the caller leaves it unset.	`25`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	Port for HTTP server.	`3010`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_SESSION_MODE`	HTTP session posture: `auto`, `stateful`, or `stateless`. The server declares `stateless` in code — no tool holds per-session state — so set this only to opt back into a session store.	`stateless`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Storage backend.	`in-memory`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation (spans, metrics, completion logs).	`false`

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

bun run devcheck   # Lint, format, typecheck, security
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t uniprot-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/uniprot-mcp-server:latest

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/uniprot-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools/resources/prompts and inits the UniProt service.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`). Six tools over UniProtKB, ID mapping, proteomes, taxonomy, and sequences.
`src/mcp-server/resources`	Resource definitions (`*.resource.ts`). Entry and taxonomy by-ID mirrors.
`src/mcp-server/prompts`	Prompt definitions (`*.prompt.ts`). The protein-dossier workflow prompt.
`src/services/uniprot`	The `rest.uniprot.org` REST client — search, batch entries, ID mapping, proteomes, taxonomy, FASTA — plus normalized domain types.
`tests/`	Unit and integration tests mirroring `src/`.

Development guide

See CLAUDE.md (and the byte-identical AGENTS.md) for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
Register new tools and resources in the createApp() arrays
Wrap the UniProt API: validate raw → normalize to domain type → return the output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Tools (6)

uniprot_search_proteinsuniprot_get_entryuniprot_map_idsuniprot_get_proteomeuniprot_get_taxonomyuniprot_get_sequence

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "uniprot-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/uniprot-mcp-server@0.2.4",
        "run",
        "start:stdio"
      ],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

@cyanheads/uniprot-mcp-server (MCP Server)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

uniprot_search_proteins

uniprot_get_entry

uniprot_map_ids

uniprot_get_proteome

uniprot_get_taxonomy

uniprot_get_sequence

@cyanheads/uniprot-mcp-server

Overview

Tools

Resources

Prompts

Capability reference

uniprot_search_proteins tool

uniprot_get_entry tool

uniprot_map_ids tool

uniprot_get_proteome tool

uniprot_get_taxonomy tool

uniprot_get_sequence tool

uniprot://entry/{accession} resource

uniprot://taxonomy/{taxonId} resource

uniprot_protein_dossier prompt

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`uniprot_search_proteins` _tool

`uniprot_get_entry` _tool

`uniprot_map_ids` _tool

`uniprot_get_proteome` _tool

`uniprot_get_taxonomy` _tool

`uniprot_get_sequence` _tool

`uniprot://entry/{accession}` _resource

`uniprot://taxonomy/{taxonId}` _resource

`uniprot_protein_dossier` _prompt