cyanheads/uniprot-mcp-server

imageVersion imageLicense imageDocker imageMCP SDK imagenpm imageTypeScript imageBun

imageInstall in Claude Desktop imageInstall in Cursor imageInstall in VS Code

imageFramework

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

Overview

Protein research over UniProtKB. Search by function or gene, fetch curated records, map identifiers from Ensembl, ChEMBL, RefSeq, PDB, and more, and pull reference proteomes, taxonomy, and sequences.

Tools

Resources

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

Agent skill

The UniProt guide covers protein identity, species versus strain scope, mapping completeness, and evidence-backed interpretation. It ships with plugin, npm, MCPB, and Docker installations and is available over MCP at skill://uniprot-guide/SKILL.md.

Capability reference

uniprot_search_proteins tool

• text_search for plain language or query for Lucene field syntax (gene, organism_id, taxonomy_id, keyword, go, reviewed, protein_name, family, length, existence, accession) — exactly one. Plain-text punctuation and uppercase Boolean words are escaped. Structured queries reject unbalanced parentheses. Optional facets return count breakdowns (e.g. reviewed, model_organism)
• The organism_id input restricts the whole query to that taxon and its descendants. For exact-node scope, use organism_id:<id> inside query instead
• reviewed defaults to true (Swiss-Prot only); false searches both tiers (put reviewed:false in query for TrEMBL only). Every hit carries reviewed, annotationScore, and proteinExistence
• Forward-only cursor pagination; returns totalResults and the effective query. Cursors bind to this tool and the exact assembled query, including organism/reviewed filters. Changing size, fields, or facets keeps continuation valid; a changed query, malformed token, or legacy raw cursor fails invalid_cursor: restart without it
• Inactive accessions (merged, demerged, or deleted) go in inactive[] with the reason and replacements, not in results[]

uniprot_get_entry tool

• Up to 20 accessions per call, from uniprot_search_proteins or uniprot_map_ids (strip any -N isoform suffix). Sectioned record: function, catalytic activity, cofactors, subcellular location, disease, PTMs, natural variants, isoforms, domains, GO terms, keywords, cross-references. fields trims the output; identity and provenance fields are always kept
• Resolved entries come back in succeeded[], unknown or inactive ones in failed[], so one bad accession doesn't abort the batch. An inactive accession's error names the merge target, the demerge products, or the UniParc ID
• Initial responses exceeding 24,000 UTF-8 bytes across content[] and structuredContent return kind: "outline". A single resolved accession returns a section listing; an oversized batch returns outlinedEntries in request order, preserving every failed[] entry. Re-call each outlined accession individually, then use sections: [...] for the parts you need. Explicit sections render every returned item, including all cross-reference IDs; a very large list section pages with section_limit (1–500) and section_offset, reporting totalCount and nextOffset

uniprot_map_ids tool

• from_db / to_db are validated enums (e.g. Gene_Name, Ensembl, RefSeq_Protein, ChEMBL, PDB, GeneID, and UniProtKB_AC-ID as a source); an unknown database fails before any request. Target UniProtKB-Swiss-Prot for reviewed accessions only, or UniProtKB to include TrEMBL. Mapping tax_id restricts submission to an exact node, excluding descendants; use the intended strain's taxon ID when needed
• Submits the job and polls within a time budget. A job still running returns status: "running" with a ticket; pass that ticket alone to poll it. A finished call returns status: "finished" with one page, and continuation (pass it alone) fetches the next; no continuation means the last page
• mappedCount counts the current page; totalMappings is UniProt's job-wide total when available. unmappedIds is UniProt's job-wide failed-ID metadata, repeated on completed pages rather than inferred from the displayed rows
• UniProtKB targets include available entry name, reviewed status, organism, and primary gene. Inactive targets carry their reason and replacements. Metadata or enrichment outages fall back to generic identifier rows with a notice; jobs above UniProt's 100,000-mapping enrichment limit remain pageable
• Terminal job failures use mapping_failed with UniProt's safe error message and recovery guidance. Only an explicitly unsupported database combination at submission uses unsupported_db_pair
• A rejected completed-page continuation (HTTP 400), unknown page, or expired job fails invalid_continuation with restart guidance. Upstream outages retain their upstream error classification

uniprot_get_proteome tool

• Provide exactly one of upid (e.g. UP000005640) or taxon_id; both or neither fails validation. Resolve an organism name to a taxon ID first with uniprot_get_taxonomy. Taxon lookup prefers an exact reference proteome, then a unique descendant reference. Multiple descendants return candidate UPIDs and organism identities for explicit selection, with a next-page link when suggestions are incomplete
• Returns proteome type, total protein count, BUSCO completeness (score, complete/fragmented/missing counts, lineage dataset), and genome assembly accession
• Proteins are opt-in via include_proteins (human has ~147,506) and come back as a capped page with a forward cursor; narrow with query (UniProtKB Lucene syntax). Cursors bind to the resolved UPID, exact query, and tool; a taxon ID and UPID resolving to the same proteome may share a cursor, and size may change. Changed membership or a legacy raw cursor fails invalid_cursor: restart without it

uniprot_get_taxonomy tool

• Provide exactly one of taxon_id (NCBI numeric ID) or name (organism name); both or neither fails validation. Gives the taxon ID that uniprot_search_proteins (organism_id) and uniprot_get_proteome (taxon_id) expect
• Name matching prefers exact case-insensitive scientific names, then common names, mnemonics, and aliases. Quote/backslash-tolerant matching follows exact matching. Ties or partial matches return candidate taxon IDs instead of selecting the first hit
• Name resolution shares a 45-second budget across candidate pages and the selected record lookup. If candidate scanning cannot finish, incomplete_candidates supplies partial suggestions and a candidate-search URL; use an explicit taxon ID or narrow the name
• Returns scientific and common name, mnemonic, rank, parent, and the full lineage (root → near ancestor)
• include_children adds the immediate child taxa, 100 per page with the total count and a cursor for the next page. A cursor sent with a different taxon fails invalid_cursor

uniprot_get_sequence tool

• Returns the canonical sequence with its length and parsed FASTA header; include_isoforms adds the isoform sequences. Accessions come from uniprot_search_proteins or uniprot_map_ids (strip any -N isoform suffix)
• A merged accession returns its merge target's sequences, with the requested accession in mergedFrom; a demerged or deleted one fails not_found naming its replacements or UniParc ID

uniprot://entry/{accession} resource

• Same record as uniprot_get_entry for a single accession, addressed by URI. An inactive accession (merged, demerged, or deleted) fails not_found
• A very large entry returns an identity summary (accession, entry name, protein name, genes, organism, length, reviewed status, annotation score, protein existence) plus a section outline; fetch specific sections with uniprot_get_entry (sections: [...]), since the URI takes no sections parameter

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)
• Batch entry fetch — N accessions in one round trip, with any missing ones flagged
• Async ID mapping with a bounded poll, a resumable ticket for running jobs, and paginated 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
• Explicit output shapes — uniprot_get_entry returns kind: "full" | "outline", and uniprot_map_ids returns either a ticket or a continuation
• 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:

{
  "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.

{
  "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):

{
  "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:

{
  "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.4.0 or higher (or Node.js v24+).
• No API key — UniProt REST is keyless and open. Data is UniProt, CC BY 4.0.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd uniprot-mcp-server

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

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 test:coverage   # Test suite with coverage, enforcing the framework thresholds
  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

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.