\n\n[](https://github.com/cyanheads/protein-mcp-server/releases/latest/download/protein-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=protein-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvcHJvdGVpbi1tY3Atc2VydmVyIl19) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22protein-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fprotein-mcp-server%22%5D%7D)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n## Tools\n\nSeven tools spanning the structure-research arc — discover, fetch, find homologs, track ligands, compare, profile the corpus, and annotate — over experimental (PDB) and predicted (AlphaFold) structures from one surface:\n\n| Tool | Description |\n|:---|:---|\n| `protein_search_structures` | Search experimental and predicted structures by free text, sequence, or organism/method/resolution filters, with optional facet breakdowns. |\n| `protein_get_structure` | Fetch metadata and coordinate-file URLs by ID — experimental (PDB), predicted (AlphaFold), or best-available — with batch partial success and optional coordinate inlining. |\n| `protein_find_similar` | Find sequence homologs (RCSB mmseqs2) or fold homologs (Foldseek) from a sequence, PDB ID, or UniProt accession. |\n| `protein_track_ligands` | Resolve ligand names/formulas to component IDs, find structures containing a ligand, or map binding-site residues. |\n| `protein_compare_structures` | Structurally align multiple structures (TM-align / jFATCAT) to a reference or as a full pairwise matrix. |\n| `protein_analyze_collection` | Profile the PDB into distributions and trends with server-side facets — counts, histograms, timelines, and cross-tabs. |\n| `protein_get_annotations` | Fetch UniProt features and natural variants plus InterPro domain/family memberships with GO terms. |\n\n### `protein_search_structures`\n\nFederated search across experimental (PDB) and predicted (computed-model) structures via RCSB Search v2.\n\n- Free-text, protein-sequence (triggers an mmseqs2 similarity search), and organism / method / resolution filters\n- `content_type` scopes the search to `experimental`, `predicted`, or `all` — the default `all` is a genuine union of both universes, so computed models appear alongside PDB entries\n- Every hit names its `source`; experimental sequence hits expose a chainable PDB entry `id` plus the matched polymer `entityId`, with title, method, resolution, and organism enrichment, while computed models retain their complete model ID and parsed UniProt accession\n- `start` and `limit` page through ranked results; `nextStart` is returned while another page remains\n- Optional `facets` return a method / organism / release-year breakdown alongside the hits at no extra call, each reporting how many matches carry no value for that dimension; each dimension may be listed once\n- Chain hit IDs straight into `protein_get_structure`\n\n---\n\n### `protein_get_structure`\n\nFetch structures with metadata and coordinate-file URLs, resolving across providers by `source`.\n\n- `source: experimental` takes PDB entry IDs, batched in one RCSB GraphQL call; it also resolves the computed-model IDs search returns (`AF_*` / `MA_*`), which come back as `source: predicted` credited to their modelling provider\n- `source: predicted` takes UniProt accessions and returns the AlphaFold model with pLDDT/PAE confidence\n- `source: best_available` takes UniProt accessions and returns the top federated model (experimental if one exists, else the best prediction)\n- Per-ID partial success — unresolved IDs are listed in `failed[]`, not a batch-level error\n- `include_coords` inlines coordinate content; when a batch overflows the response budget it returns a per-structure size outline, so you can re-call with `sections: [ids]` for specific structures\n- Every response carries an `attribution` block naming the upstream data licenses and citations (see [Upstream data licensing](#upstream-data-licensing))\n\n---\n\n### `protein_find_similar`\n\nFind structurally or evolutionarily related proteins, by sequence or by fold.\n\n- `by: sequence` runs a synchronous RCSB mmseqs2 search; `by: structure` runs an asynchronous Foldseek search against experimental and predicted databases\n- Query from a raw one-letter sequence, a PDB ID, or a UniProt accession\n- Sequence searches accept `start` with `limit` and return `nextStart` while another page remains\n- Foldseek targets default to `pdb100` + `afdb50`; override via `databases` (e.g. `afdb-swissprot`, `BFVD`)\n- Async jobs that exceed the poll budget return `status: computing` with a `ticketId` — re-call with `ticket_id` set to that value to poll the same job instead of resubmitting\n- Each hit names the engine and source database it came from\n\n---\n\n### `protein_track_ligands`\n\nLigand discovery and binding-site analysis across the PDB.\n\n- `mode: find_ligand` resolves a name or formula to chemical component IDs with formula, weight, SMILES, and InChIKey\n- `mode: structures_with_ligand` returns PDB entries containing a ligand by exact component ID\n- `mode: structures_with_ligand` accepts `start` with `limit` and returns `nextStart` while another page remains\n- `mode: binding_site` returns the protein residues lining a ligand's pocket in a structure, with contact distances\n- Binding sites are experimental-only — computed from deposited coordinates (predicted models carry no bound ligands)\n\nPaged RCSB results preserve the upstream order within each response. Resolution ties and changes in the live corpus mean traversal is best-effort across calls, not a stable export snapshot.\n\n---\n\n### `protein_compare_structures`\n\nStructural alignment of multiple structures (up to the configured `PROTEIN_MAX_COMPARE_STRUCTURES` cap) via the RCSB Structural Comparison service.\n\n- Methods: `tm-align`, `fatcat-rigid`, `fatcat-flexible`\n- `reference: first` aligns every structure to the first; `reference: all_pairs` computes the full pairwise matrix\n- Optional per-structure `chain` restricts the alignment to a single chain\n- A structure repeated in `structures[]` is compared once — the repeat would only add a self-alignment and a mirrored pair, which the resume mechanism cannot tell apart from the original\n- Each pair is an independent async job, fanned out with a concurrency cap and per-pair partial success — a pair still computing when the budget elapses returns `status: computing` with its job `uuid`, and a failed pair degrades its row without sinking the others\n- Re-call with a matching `{ a, b, uuid }` entry in `resume[]` (copied from a prior response's `pairs[]`) to poll a computing pair's job instead of resubmitting\n- Returns TM-score, RMSD, and aligned-residue count per pair, plus `modeledResidues` and `coverage` — each a `[a, b]` tuple, with coverage a 0–100 percentage of that structure's own modeled-residue count\n\n---\n\n### `protein_analyze_collection`\n\nProfile the PDB into distributions and trends over an optional scoping query — backed by RCSB's server-side facet engine (one call, compact buckets, no row pull).\n\n- Group by `method`, `organism`, `polymer_type`, `resolution`, `release_year`, or `molecular_weight`\n- One `group_by` dimension for a breakdown, or two distinct dimensions for a cross-tab (the first nests the second); a repeated dimension is rejected\n- `interval` sets the bin width for value histograms or the period for date histograms (`year` / `month` / `quarter`)\n- Scope with a free-text `query`, `organism`, `method`, or `max_resolution`; `content_type` selects the structure universe\n- `bucket_limit` caps buckets per dimension level, not per response — a cross-tab applies it separately to the parent dimension and to the nested child inside each parent bucket, so up to `bucket_limit × (1 + bucket_limit)` buckets come back. Each level flags its own truncation, and `bucketsReturned` gives the realized total\n- Every dimension reports `missingValueCount` — matches in scope carrying no value for that attribute, which therefore fall in no bucket (a `resolution` breakdown does not cover NMR entries, and neither `method` nor `resolution` covers computed models)\n\n---\n\n### `protein_get_annotations`\n\nSequence and functional annotation for a protein.\n\n- UniProt features (domains, binding sites, PTMs) and natural sequence variants\n- InterPro domain/family memberships (Pfam, PROSITE, …) with associated GO terms\n- Provide a UniProt accession directly, or a PDB ID — resolved to a UniProt accession via the structure's sequence cross-reference\n- A multi-chain PDB entry can map to several accessions; the default is the deterministic lowest-author-chain pick, with the alternatives listed under `ambiguity`. Pass `chain` (an author chain ID, e.g. `A`) to select a specific one\n- `include` scopes which annotation classes are fetched: `features`, `domains`, `variants`, or `all`\n- Every response carries an `attribution` block naming the upstream data licenses and citations (see [Upstream data licensing](#upstream-data-licensing))\n\n## Resources\n\n| Type | Name | Description |\n|:---|:---|:---|\n| Resource | `pdb://{entry_id}` | Experimental structure summary for a PDB entry — title, method, resolution, organism, chains, and bound ligands. |\n| Resource | `af://{uniprot}` | Predicted-structure summary for a UniProt accession from AlphaFold DB — mean pLDDT, confidence-band fractions, model URLs, and version. |\n\nAll resource data is also reachable via tools — `pdb://{entry_id}` mirrors `protein_get_structure` for `source: experimental`, and `af://{uniprot}` mirrors it for `source: predicted`. Many MCP clients are tool-only and don't surface resources; the summaries remain reachable through the tools.\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool and resource 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\nProtein-specific:\n\n- One federated surface over experimental (PDB) and predicted (AlphaFold / 3D-Beacons) structures — search, fetch, and compare treat both universes the same\n- Keyless across every upstream — RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro, and Foldseek, no API keys to provision\n- Corpus analytics run server-side on RCSB's facet engine — distributions, histograms, and cross-tabs in one call, no row pull and no SQL workspace\n- Async alignment and Foldseek jobs poll within a bounded budget and hand back a job ticket (`ticketId` / per-pair `uuid`) instead of blocking — re-call with `ticket_id` or a `resume[]` entry to poll the same job instead of resubmitting\n\nAgent-friendly output:\n\n- Provenance on every response — each hit carries a `source` (`experimental` / `predicted`), the engine and database that produced it, and effective-query / total-count echoes so agents can reason about coverage\n- Graceful partial failure — batch fetches and pairwise comparisons return per-item rows (`failed[]`, per-pair `status`) instead of failing the whole request, each with actionable recovery text\n- Discriminated output contracts — typed `source` and `status` unions, `computing` results with resume tickets, and budget-overflow outlines let callers branch on data, not string parsing\n\n## Getting started\n\n### Public Hosted Instance\n\nA public instance is available at `https://protein.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:\n\n```json\n{\n \"mcpServers\": {\n \"protein\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://protein.caseyjhand.com/mcp\"\n }\n }\n}\n```\n\n### Self-hosted\n\nAdd the following to your MCP client configuration file. No API key is required — every upstream provider is keyless.\n\n```json\n{\n \"mcpServers\": {\n \"protein-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/protein-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 \"protein-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/protein-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 \"protein-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"-e\", \"MCP_TRANSPORT_TYPE=stdio\", \"ghcr.io/cyanheads/protein-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.2](https://bun.sh/) or higher (or Node.js v24+).\n- No accounts or API keys — RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro, and Foldseek are all public and keyless.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/protein-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd protein-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n## Configuration\n\nAll upstream providers are keyless, so the server runs out of the box with no configuration. Every variable below is optional.\n\n| Variable | Description | Default |\n|:---|:---|:---|\n| `PROTEIN_ASYNC_POLL_TIMEOUT_MS` | Max wall-clock to poll an async job (alignment / Foldseek) before returning a `computing` result. | `30000` |\n| `PROTEIN_MAX_BATCH_IDS` | Cap on IDs accepted by `protein_get_structure` in one batch (1–100). | `25` |\n| `PROTEIN_MAX_COMPARE_STRUCTURES` | Cap on structures per `protein_compare_structures` call (2–25). | `10` |\n| `PROTEIN_FACET_BUCKET_CAP` | Default cap on buckets per `protein_analyze_collection` dimension (1–500). | `50` |\n| `PROTEIN_FANOUT_CONCURRENCY` | Max concurrent upstream requests for per-ID / per-pair fan-out (1–16). | `5` |\n| `RCSB_SEARCH_BASE_URL` | Base URL for the RCSB Search API v2. | `https://search.rcsb.org` |\n| `ALPHAFOLD_BASE_URL` | Base URL for the AlphaFold Protein Structure Database API. | `https://alphafold.ebi.ac.uk` |\n| `FOLDSEEK_BASE_URL` | Base URL for the Foldseek structural-similarity search service. | `https://search.foldseek.com` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of provider base-URL overrides and tuning limits.\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 protein-mcp-server .\ndocker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 protein-mcp-server\n```\n\nThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/protein-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 and inits the provider services. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). |\n| `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). |\n| `src/services` | Provider service layer — RCSB, AlphaFold, 3D-Beacons, UniProt, InterPro, Foldseek, and shared HTTP/identifier helpers. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`/`AGENTS.md`](./CLAUDE.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 via the barrels in `src/mcp-server/*/definitions/index.ts`\n- Wrap external API calls: validate raw → normalize to domain type → return 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## Upstream data licensing\n\nStructure and annotation data comes from public upstream databases, each under its own license. `protein_get_structure` and `protein_get_annotations` carry an `attribution` block on every response — the license, citation, and homepage for each source that contributed to that specific response — so the attribution obligation travels with the data to downstream consumers rather than living only here. CC BY / CC BY-SA sources require attribution on redistribution; CC0 sources are citation-only (attribution encouraged, not required).\n\n| Source | Contributes to | License |\n|:---|:---|:---|\n| [RCSB PDB](https://www.rcsb.org/) | `protein_get_structure` — experimental records | CC0 1.0 Universal |\n| [AlphaFold DB](https://alphafold.ebi.ac.uk/) | `protein_get_structure` — predicted models | CC BY 4.0 |\n| [ModelArchive](https://www.modelarchive.org/) | `protein_get_structure` — `MA_*` computed models | CC BY 4.0 |\n| [SWISS-MODEL](https://swissmodel.expasy.org/) | `protein_get_structure` — `best_available` models | CC BY-SA 4.0 |\n| [BFVD](https://bfvd.steineggerlab.workers.dev/) | `protein_get_structure` — `best_available` models | CC BY 4.0 |\n| [UniProt](https://www.uniprot.org/) | `protein_get_annotations` | CC BY 4.0 |\n| [InterPro](https://www.ebi.ac.uk/interpro/) | `protein_get_annotations` — domain/family data | CC0 1.0 Universal |\n| [GO](https://geneontology.org/) | `protein_get_annotations` — GO terms | CC BY 4.0 |\n\n`best_available` federates predicted models through [3D-Beacons](https://3d-beacons.org/), so the `attribution` block credits the actual contributing provider (AlphaFold DB, SWISS-MODEL, BFVD, …); a provider without a curated license entry carries a `See provider terms` fallback pointing back to 3D-Beacons rather than a fabricated license. InterPro's own domain/family classifications are CC0; the GO terms carried alongside them are separately CC BY 4.0, so each is credited independently only when it actually contributes. Full citations for each source travel in the `attribution` block of the relevant tool responses. This covers upstream *data* licensing — the server's own code is licensed separately (see [License](#license)).\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n",
"bytes": 21172,
"sha": "21947d94e06c234237ad7574c1ba4ba5b3855137dc79717f0f9c0c96523ed2ec",
"repo_slug": "cyanheads/protein-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_protein_mcp_server_1098ce7b/readme"
}