Tools

Seven 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:

protein_search_structures

Federated search across experimental (PDB) and predicted (computed-model) structures via RCSB Search v2.

• Free-text, protein-sequence (triggers an mmseqs2 similarity search), and organism / method / resolution filters
• 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
• 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
• start and limit page through ranked results; nextStart is returned while another page remains
• 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. A dimension whose buckets hit the server-side cap is named in notice, with protein_analyze_collection and a larger bucket_limit as the route to the long tail (a sequence search gets a narrowing step instead, since that tool has no sequence input)
• Chain hit IDs straight into protein_get_structure

protein_get_structure

Fetch structures with metadata and coordinate-file URLs, resolving across providers by source.

• 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
• source: predicted takes UniProt accessions and returns the AlphaFold model with pLDDT/PAE confidence
• source: best_available takes UniProt accessions and returns the top federated model (experimental if one exists, else the best prediction)
• Per-ID partial success — unresolved IDs are listed in failed[], not a batch-level error
• Batch cap disclosure — requested is the original request length and processed the count after the cap, so IDs dropped beyond the cap are visible rather than silently discarded; every advisory (cap, partial failure, coordinate overflow, failed inlining) is joined into one notice
• Records served by the RCSB entry endpoint also carry polymerEntities (with both authAsymIds and labelAsymIds), ligands, molecularWeight, and releaseDate
• include_coords inlines coordinate content, subject to the response budget: a batch over budget returns a per-structure size outline you can re-call with sections: [ids], and a single file over budget is withheld with a pointer to its coordinateUrls (a sections re-call would return the same bytes). A sections re-call is not re-gated — structuredContent carries the named payload whole at any size, while the token-bounded text surface withholds anything over the budget and points at coordinateUrls instead of truncating it
• Every response carries an attribution block naming the upstream data licenses and citations (see Upstream data licensing)

protein_find_similar

Find structurally or evolutionarily related proteins, by sequence or by fold.

• by: sequence runs a synchronous RCSB mmseqs2 search; by: structure runs an asynchronous Foldseek search against experimental and predicted databases
• Query from a raw one-letter sequence, a PDB ID, or a UniProt accession
• Both modes accept start with limit and report totalCount, echoing start and returning nextStart while another page remains
• Foldseek targets default to pdb100 + afdb50; override via databases (e.g. afdb-swissprot, BFVD)
• 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. A completed structure search returns the same ticket, so a new start pages the finished job without resubmitting the structure
• Each mode reads only its own controls — sequence, max_evalue and min_identity under by: sequence; ticket_id and databases under by: structure; pdb_id, uniprot, start and limit shared — and a field the selected mode cannot consume is rejected rather than ignored
• Each hit names the engine and source database it came from

protein_track_ligands

Ligand discovery and binding-site analysis across the PDB.

• mode: find_ligand resolves a name or formula to chemical component IDs with formula, weight, SMILES, and InChIKey
• A formula-shaped query matches on exact composition — spaced (C29 H31 N7 O) or unspaced (C29H31N7O), either resolves the same component; anything else, a component ID included, matches on name and synonyms and is ranked by deposition frequency
• mode: structures_with_ligand returns PDB entries containing a ligand by exact component ID
• mode: structures_with_ligand accepts start with limit and returns nextStart while another page remains
• mode: binding_site returns the protein residues lining a ligand's pocket in a structure, with contact distances
• Binding sites are experimental-only — computed from deposited coordinates (predicted models carry no bound ligands)

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

protein_compare_structures

Structural alignment of multiple structures (up to the configured PROTEIN_MAX_COMPARE_STRUCTURES cap) via the RCSB Structural Comparison service.

• Methods: tm-align, fatcat-rigid, fatcat-flexible
• reference: first aligns every structure to the first; reference: all_pairs computes the full pairwise matrix
• Optional per-structure chain restricts the alignment to a single chain
• 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
• 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
• 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
• 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

protein_analyze_collection

Profile 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).

• Group by method, organism, polymer_type, resolution, release_year, or molecular_weight
• 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
• interval sets the bin width for a value histogram (a number, for resolution or molecular_weight) or the period for a date histogram (year — the only period RCSB accepts). It applies to whichever requested group_by dimension can consume that value type, primary or nested child, so ["method", "resolution"] bins its nested resolution child; when both dimensions can consume it the primary takes it and the child keeps its default, and when neither can the call is rejected rather than silently ignoring the override
• Scope with a free-text query, organism, method, or max_resolution; content_type selects the structure universe
• 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, notice names every capped position (the top-level dimension and each nested child, with how many parent buckets it was capped under), and bucketsReturned gives the realized total
• 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)

protein_get_annotations

Sequence and functional annotation for a protein.

• UniProt features (domains, binding sites, PTMs) and natural sequence variants
• InterPro domain/family memberships (Pfam, PROSITE, …) with associated GO terms
• Provide a UniProt accession directly, or a PDB ID — resolved to a UniProt accession via the structure's sequence cross-reference
• 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
• include scopes which annotation classes are fetched: features, domains, variants, or all
• Every response carries an attribution block naming the upstream data licenses and citations (see Upstream data licensing)

Resources

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

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

Protein-specific:

• One federated surface over experimental (PDB) and predicted (AlphaFold / 3D-Beacons) structures — search, fetch, and compare treat both universes the same
• Keyless across every upstream — RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro, and Foldseek, no API keys to provision
• 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
• 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

Agent-friendly output:

• 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
• 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
• 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

Getting started

Public Hosted Instance

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

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

Self-hosted

Add the following to your MCP client configuration file. No API key is required — every upstream provider is keyless.

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

Or with npx (no Bun required):

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

Or with Docker:

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/protein-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.2 or higher (or Node.js v24+).
• No accounts or API keys — RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro, and Foldseek are all public and keyless.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd protein-mcp-server

3. Install dependencies:

bun install

Configuration

All upstream providers are keyless, so the server runs out of the box with no configuration. Every variable below is optional.

See .env.example for the full list of provider base-URL overrides and tuning limits.

Running the server

Local development

• Build and run:

  sh

  Copy

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  sh

  Copy

  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 protein-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 protein-mcp-server

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

Project structure

Development guide

See CLAUDE.md/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 via the barrels in src/mcp-server/*/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

Upstream data licensing

Structure 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).

best_available federates predicted models through 3D-Beacons, 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

Apache-2.0 — see LICENSE for details.