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.\n
\n\n[](https://github.com/cyanheads/uniprot-mcp-server/releases/latest/download/uniprot-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=uniprot-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvdW5pcHJvdC1tY3Atc2VydmVyIl19) [](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)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n## Tools\n\nSix tools for protein-first research over UniProt — discovery search is the entry point, `uniprot_map_ids` is the bridge that turns any sibling identifier into a UniProtKB accession, and the rest fetch curated records, proteomes, taxonomy, and sequences:\n\n| Tool | Description |\n|:---|:---|\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n| `uniprot_get_taxonomy` | Resolve a taxonomy record by NCBI taxon ID or scientific name — name, rank, parent, full lineage, and optionally the immediate children. |\n| `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. |\n\n### `uniprot_search_proteins`\n\nSearch UniProtKB and return curated protein records — the discovery entry point.\n\n- `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\n- `reviewed` defaults to `true` (Swiss-Prot only) so the agent isn't drowned in TrEMBL predictions; set `false` to include them\n- `organism_id` convenience filter ANDed onto the query\n- Optional `facets` for server-side count breakdowns (e.g. `reviewed`, `model_organism`)\n- Forward cursor pagination (UniProtKB has no offset paging); `totalResults` and the effective query echoed back\n- Every hit carries `reviewed`, `annotationScore`, and `proteinExistence` so curation quality is weighable\n\n---\n\n### `uniprot_get_entry`\n\nFetch full curated UniProtKB entries by accession in batch — this tool does not search.\n\n- Batch up to 20 accessions in one round trip\n- Sectioned record: function, catalytic activity, cofactors, subcellular location, disease, PTMs, natural variants, isoforms, domains, GO terms, keywords, cross-references\n- Partial-success output — resolved entries in `succeeded[]`, unknown/withdrawn ones in `failed[]`; the whole batch never aborts on one bad accession\n- `fields` trims the upstream projection; identity and provenance fields are always retained\n- 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\n- Accessions come from `uniprot_search_proteins` or `uniprot_map_ids`; strip any `-N` isoform suffix first\n\n---\n\n### `uniprot_map_ids`\n\nTranslate identifiers across databases via UniProt's ID-mapping service — the bridge from any sibling server's identifier into a UniProtKB accession.\n\n- `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\n- Target `UniProtKB-Swiss-Prot` for reviewed accessions only (the usual intent), or `UniProtKB` / `UniProtKB_AC-ID` to include unreviewed TrEMBL\n- 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\n- A completed call returns `status: \"finished\"` with one upstream page (up to 500 mappings). If `continuation` is present, pass it alone to fetch the next completed page without polling or re-submitting; its absence marks the terminal page\n- Pair a gene-symbol `from_db` with `tax_id` to disambiguate species\n- `unmappedIds` is populated only from UniProt's `failedIds`, so identifiers UniProt normalizes in successful result rows are not misclassified as failures\n\n---\n\n### `uniprot_get_proteome`\n\nFetch the reference proteome for an organism by UPID or NCBI taxon ID — provide exactly one.\n\n- Metadata inline: proteome type, total protein count, BUSCO completeness (score, complete/fragmented/missing counts, lineage dataset), genome assembly accession\n- 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\n- Narrow the protein list with the `query` filter (UniProtKB Lucene syntax) for a subset\n- Resolve an organism name to a taxon ID first with `uniprot_get_taxonomy`\n\n---\n\n### `uniprot_get_taxonomy`\n\nResolve a taxonomy record by NCBI taxon ID or scientific name — provide exactly one.\n\n- Returns scientific and common name, mnemonic, rank, parent, and the full lineage (root → near ancestor)\n- `include_children` fetches the immediate child taxa via a follow-up search (not inline on the record)\n- Turns an organism name into the taxon ID that `uniprot_search_proteins` (`organism_id`) and `uniprot_get_proteome` (`taxon_id`) expect\n\n---\n\n### `uniprot_get_sequence`\n\nFetch the canonical amino-acid sequence (FASTA) for an accession — the cheap, sequence-only path (for the full functional record use `uniprot_get_entry`).\n\n- Returns the canonical sequence with its length and parsed FASTA header\n- `include_isoforms` also returns the alternatively-spliced isoform sequences\n- Accessions come from `uniprot_search_proteins` or `uniprot_map_ids`; strip any `-N` isoform suffix first\n\n## Resources and prompts\n\n| Type | Name | Description |\n|:---|:---|:---|\n| Resource | `uniprot://entry/{accession}` | A curated UniProtKB entry by accession — the resource mirror of `uniprot_get_entry` for a single accession. |\n| Resource | `uniprot://taxonomy/{taxonId}` | A taxonomy record by NCBI taxon ID — name, rank, parent, full lineage. The mirror of `uniprot_get_taxonomy` by ID. |\n| Prompt | `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. |\n\nAll 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.\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nUniProt-specific:\n\n- Keyless — UniProt REST requires no API key; works against any `rest.uniprot.org`-compatible base (override `UNIPROT_BASE_URL` for a private mirror)\n- One thin `fetch` client over all four REST collections (UniProtKB, ID Mapping, Proteomes, Taxonomy) with retry/backoff and HTML-error-page detection\n- Batch entry fetch — N accessions in one round trip, cross-referenced against the request to flag any missing\n- Async ID-mapping run → poll bounded by a wall-clock budget, with a running-job ticket and separately paginated completed results\n\nAgent-friendly output:\n\n- 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\n- Graceful partial failure — `uniprot_get_entry` returns per-accession `succeeded[]` / `failed[]` rows instead of aborting the batch\n- 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\n- Sparsity preserved — absent upstream fields stay absent, never fabricated (most curated sections are legitimately missing on TrEMBL entries)\n\n## Getting started\n\n### Public Hosted Instance\n\nA public instance is available at `https://uniprot.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:\n\n```json\n{\n \"mcpServers\": {\n \"uniprot-mcp-server\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://uniprot.caseyjhand.com/mcp\"\n }\n }\n}\n```\n\n### Self-Hosted / Local\n\nAdd the following to your MCP client configuration file. UniProt REST is keyless — no API key required.\n\n```json\n{\n \"mcpServers\": {\n \"uniprot-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/uniprot-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"uniprot-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/uniprot-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"uniprot-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"-e\", \"MCP_TRANSPORT_TYPE=stdio\", \"ghcr.io/cyanheads/uniprot-mcp-server:latest\"]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).\n- No API key — UniProt REST is keyless and open. Data is [UniProt](https://www.uniprot.org), CC BY 4.0.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/uniprot-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd uniprot-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n## Configuration\n\nAll 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.\n\n| Variable | Description | Default |\n|:---|:---|:---|\n| `UNIPROT_BASE_URL` | UniProt REST base URL. Override for a private mirror or testing. | `https://rest.uniprot.org` |\n| `UNIPROT_TIMEOUT_MS` | Per-request HTTP timeout in ms. | `30000` |\n| `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` |\n| `UNIPROT_DEFAULT_PAGE_SIZE` | Default page size for search and proteome protein listing when the caller leaves it unset. | `25` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `LOGS_DIR` | Directory for log files (Node.js only). | `/logs` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend. | `in-memory` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t uniprot-mcp-server .\ndocker run --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/uniprot-mcp-server:latest\n```\n\nThe 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.\n\n## Project structure\n\n| Directory | Purpose |\n|:---|:---|\n| `src/index.ts` | `createApp()` entry point — registers tools/resources/prompts and inits the UniProt service. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Six tools over UniProtKB, ID mapping, proteomes, taxonomy, and sequences. |\n| `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). Entry and taxonomy by-ID mirrors. |\n| `src/mcp-server/prompts` | Prompt definitions (`*.prompt.ts`). The protein-dossier workflow prompt. |\n| `src/services/uniprot` | The `rest.uniprot.org` REST client — search, batch entries, ID mapping, proteomes, taxonomy, FASTA — plus normalized domain types. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) (and the byte-identical [`AGENTS.md`](./AGENTS.md)) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools and resources in the `createApp()` arrays\n- Wrap the UniProt API: validate raw → normalize to domain type → return the output schema; never fabricate missing fields\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n",
"bytes": 16662,
"sha": "6983082d3d5b6acff84082bec54a970cbf0e3e2469a3a4aeaf9907235fd35fc5",
"repo_slug": "cyanheads/uniprot-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_uniprot_mcp_server_c1fea2a3/readme"
}