protein-mcp-server
Allows using Cloudflare KV, R2, and D1 as storage backends for the MCP server.
Supports OpenTelemetry tracing for observability.
Allows using Supabase as a storage backend for the MCP server.
Public Hosted Server: https://protein.caseyjhand.com/mcp
Overview
Experimental (PDB) and predicted (AlphaFold) protein structures behind one surface. Search, fetch, align, and annotate structures and their ligands across RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro, and Foldseek. No API key required.
Tools
Tool | Description |
| Search experimental and predicted structures by text, sequence, or organism/method/resolution, with optional facets |
| Fetch metadata and coordinate URLs for experimental, predicted, or best-available structures |
| Find sequence homologs (RCSB mmseqs2) or fold homologs (Foldseek) |
| Resolve ligands to component IDs, find structures containing one, or map its binding site |
| Align structures with TM-align or jFATCAT, against a reference or all pairs |
| Profile the PDB as counts, histograms, timelines, and cross-tabs |
| Fetch UniProt features and variants plus InterPro domains with GO terms |
Resources
Resource | Description |
| Experimental structure summary for a PDB entry |
| AlphaFold DB predicted-structure summary for a UniProt accession |
Both resources are also reachable through protein_get_structure, for clients that don't surface resources.
Skills
Skill | Description |
| Identifier forms each tool takes, author vs label chains, residue numbering, and the gates for |
Served over MCP as skill://protein-guide/SKILL.md; it also ships in plugin installs, the .mcpb bundle, the npm package, and the Docker image.
Related MCP server: UniProt MCP Server
Capability reference
protein_search_structures tool
At least one of
query,sequence(an mmseqs2 search;min_identity/max_evalueapply only with it),organism,method,max_resolution, orligand(an exact component ID held as a bound copy);content_typeisexperimental,predicted, orall(default); up to 100 hits per page (default 25) vialimit/startorganismtakes a scientific name, an NCBI common name, or a taxon ID, and matches that taxon plus every taxon under it; a word fragment matches nothing.methodtakes one of the 13 RCSB experimental methods in any letter case, or an alias (cryo-EM,cryoEM,EM,X-ray,xray,NMRfor both NMR methods); anything else fails asunknown_methodA
sequenceneeds at least 10 residues; whitespace is stripped and case normalized, and an invalid one fails asinvalid_sequence. Each hit names itssourceand an entryidyou can pass to other tools, and carriesorganisms(a sequence hit's are the matched entity's). Sequence hits addidentity,evalue,bitscore, and the aligned ranges, withqueryLengthat the response levelA
sequenceundercontent_type: allsearches each universe on its own and merges the hits bybitscore:totalCountis the two totals summed, andscoreandevaluehold only within a hit's own universe, so compare across universes bybitscoreoridentity. A universe whose search fails or hasn't answered in 35 s is left out, andnoticesays so. RCSB stops a sequence search at 2,000 hits, so a count that reaches it is the ceiling, not a complete count, andnoticesays that tooOptional
facets(method,organism,polymer_type,resolution,release_year,molecular_weight) add a breakdown capped atPROTEIN_FACET_BUCKET_CAPbuckets per dimension (summed across universes for a merged sequence search); facets count the filtered set, so an active organism or method filter constrains its own facet
protein_get_structure tool
source: experimental(default) takes PDB entry IDs and theAF_*/MA_*computed-model IDs search returns (these come back assource: predicted);predictedtakes UniProt accessions, isoform accessions (P04637-2), or AlphaFold DB entry IDs (AF-P04637-2-F1) for AlphaFold models with pLDDT/PAE;best_availabletakes the same identifiers (an entry ID reduces to its accession) and returns the PDB entry with the widest UniProtcoverage(ties to the finest resolution), else the model with the highest confidence on the lDDT scale. Best-available records carrycoverage,uniprotStart, anduniprotEnd; a pick can come from a non-PDB provider, and only a record withpdbIdis a PDB entry. When the federated summary lists no PDBe model, PDBe's SIFTS mapping supplies the PDB entries (one attempt, capped at 15 s; skipped for an isoform accession, whose pick stays among the models 3D-Beacons lists for it). If that check is unavailable, the pick ranks the federated models alone andnoticesays soA UniProt accession merged into another entry resolves to its successor's model with a
notice; a demerged or deleted one lands infailed[]with its replacementsIDs are trimmed and de-duplicated (case-insensitive); up to
PROTEIN_MAX_BATCH_IDSare looked up per call (default 25) and the remainder comes back inignored. One 50 s budget covers all upstream lookups in a call; underpredictedandbest_available, an ID it stops, or whose upstream lookup fails (an error status, an HTML page, a network failure), lands infailed[]with a reason to re-call itUnresolved IDs land in
failed[]; when nothing resolves the call fails asupstream_unavailable(retryable, withdata.failed) if every ID's lookup failed upstream or ran out of the 50 s budget, so none is known to lack a structure, and otherwise asall_failed(withdata.failed); it failsmixed_id_typeswhen the IDs don't fitsource. Records includecoordinateUrlsfor the files that exist, andorganismsunderexperimentalandpredictedUnder
experimental, each polymer entity lists its first 100 chain IDs per namespace (authAsymIds,labelAsymIds) besidechainCount;all_chains: truelists every chain, andnoticenames the structures it capped. Thepdb://resource always lists every chaininclude_coordsinlines coordinate text in 24,000-character windows: a single selected structure pages withcoords_offset, passing backcoordinatesNextOffsetuntil it is absent; several selected files inline whole only when together they fit one window, otherwise anoverflowoutline lists each file's length to re-call withsections: [id].coords_offsetabove 0 needs exactly one selected structure (coords_offset_needs_one_structure)
protein_find_similar tool
by: sequenceruns a synchronous RCSB mmseqs2 search over experimental PDB entries only (protein_search_structureswith asequencealso reaches computed models) fromsequence,pdb_id, oruniprot, filtered bymax_evalue/min_identity;by: structureruns an async Foldseek search frompdb_id(its mmCIF file) oruniprot(its AlphaFold DB model) againstpdb100+afdb50unlessdatabasessays otherwise.uniprottakes a canonical or isoform accession, or a UniProtKB entry name such asHBA_HUMAN(resolved to its entry's accession), in both modes and is shape-checked before any request (invalid_accession).databasestakes exactly these case-sensitive names:pdb100,afdb50,afdb-swissprot,afdb-proteome,bfvd_v3,cath50,mgnify_esm30,gmgcl_id,bfmd; any other fails schema validation (-32602), and a name Foldseek itself refuses fails asdatabases_rejected. A field only the other mode reads fails asmode_mismatched_field; up to 100 hits per page (default 25)Sequences follow the same rules as
protein_search_structures, and a directsequencewins over identifiers. Apdb_idsequence query searches one protein entity: the one holdingchain(author chain, case-sensitive,by: sequenceonly, requirespdb_id), else the lowest-numbered protein entity of at least 10 residues; DNA and RNA entities are never searched. The response names it inqueryEntityId, and a notice lists the entry's other protein entities. An unmatchedchainfails aschain_not_found, andchainwithoutpdb_idaschain_without_pdb_idHits name their
source(anddatabasefor structure hits), ranked byscore; sequence hits addidentity,evalue,bitscore, and the aligned ranges. Responses reporttotalCount,nextStart, andqueryLength; aby: sequencetotalCountof exactly 2,000 is RCSB's hit ceiling, not a complete count, andnoticesays soA merged
uniprotaccession answers for its successor with a notice; a demerged or deleted one fails asinactive_accessionwith its replacements. Aby: structurecoordinate file is limited to 16,000,000 characters, and a larger one fails asstructure_too_largeA structure hit carries Foldseek's
targetname and anidonly when the target resolves to a PDB entry or UniProt accession;bfvd_v3,mgnify_esm30,gmgcl_id, andbfmdhits have none. Other structure-hit fields:chain(a-Nsuffix marks a symmetry copy),title,probability,organisms/taxId(the target's, where Foldseek classifies it), and the aligned spansqueryStart,queryEnd,targetStart,targetEnd,targetLength. A sequence hit'sorganismsare the matched entity'sA structure job still running at the poll budget returns
status: computingwith aticketId; re-call withby: structureandticket_id(plus the samequerywhen it isn't 0) to resume it. A job Foldseek accepted before the call's 50 s budget ran out comes back the same way. For a new search the poll window starts when the call does, so identifier lookups and the coordinate download come out of it. A multichain structure is searched one chain at a time viaquery(0-based, default 0) out ofqueryCount
protein_track_ligands tool
modeisfind_ligand(query: a name or formula),structures_with_ligand(comp_id), orbinding_site(pdb_id, optionalcomp_id); a missing mode input fails asmissing_param.limitis 1–100 (default 25), andstartpages every mode. Each call stops at a 50 s upstream budgetfind_ligandreturns component IDs with formula, weight, SMILES, and InChIKey, ranked bydepositionCountwithin blocks ofmax(limit, 25)name matches in RCSB's name-match order, sostartpages the blocks (keeplimitfixed between pages) andtotalCountandcandidatesConsideredshow how many components matched and how many the page ranked;structures_with_ligandlists entries highest resolution first, each withtitle,method, andhostEntities(the polymer entities whose chains the depositor assigned the ligand to), and a zero-hitnoticesays whether the ID is a chemical component at allMatching counts bound non-polymer copies only, not a residue inside a polymer chain or a sugar inside a branched glycan;
depositionCountequals thetotalCountofstructures_with_ligandfor the same componentbinding_sitereturns the polymer residues (amino acids or nucleotides) lining a ligand's pocket with contact distances, numbered in both label (asymId,seqId) and author (authAsymId,authSeqId) namespaces, for ligand instances in a fixed order (ligand entity number, author chain, author residue number) sostart/limitpages read each once; it works on experimental structures only and covers non-polymer ligands, so a ligand deposited as a polymer chain (a BIRD molecule such as cyclosporin A in 1CWA) has no pocket. A miss failsnot_foundand names the components the entry holds and any polymer-chain ligands
protein_compare_structures tool
2 structures up to
PROTEIN_MAX_COMPARE_STRUCTURES(default 10, max 25), each apdb_idwith an optional label-namespacechain;methodistm-align(default),fatcat-rigid, orfatcat-flexible;referenceisfirst(default) orall_pairs;timeout_s(5–120) sets the per-pair poll budget, and the call's 50 s budget ends polling first oncetimeout_snears 50 or the pairs outnumberPROTEIN_FANOUT_CONCURRENCY: a pair it stops after submission returnscomputing, and one it reaches before submission returnsfailedEach pair row has a
status(complete,computing,failed),tmScore,rmsd,alignedResidues,modeledResidues, andcoverage; TM-score is normalized bya's length, so reversing a pair changes it.similarityScoreandsequenceSimilarityappear when the upstream supplies themStructures past the cap return in
ignoredas{ pdb_id, chain? }, not compared. A computing pair, and a failed pair whose job was submitted, return its jobuuid; re-call with the samestructures,reference, andmethodplus{ a, b, uuid }inresume[]to poll it instead of resubmitting. A mismatchedmethodor pair fails asresume_method_mismatchorresume_job_mismatch
protein_analyze_collection tool
group_bytakes one ofmethod,organism,polymer_type,resolution,release_year,molecular_weight, or two distinct ones for a cross-tab; scope withquery,organism,method,max_resolution, andcontent_type(defaultexperimental);organismandmethodtake the same forms as inprotein_search_structures, and an unknownmethodfails asunknown_method.intervalsets a numeric bin width forresolution/molecular_weightor"year"forrelease_yearReturns
totalandbucketsReturned; buckets carrylabelandcount(numeric bins addrangeFrom/rangeTo), and every dimension reportsmissingValueCountbucket_limit(1–500, defaultPROTEIN_FACET_BUCKET_CAP) caps each dimension separately;truncatedandnoticesay where results were cutThe call stops at a 50 s upstream budget; a hung facet request fails as
Timeout
protein_get_annotations tool
A canonical
uniprotaccession, or apdb_idresolved through its UniProt cross-reference (authorchainpicks one accession);includeisfeatures,domains,variants, orall(default);limitpages each class separately (1–200, default 50), with independent zero-basedfeatures_offset,variants_offset, anddomains_offset(default 0)Returns UniProt features (domains, binding and active sites, PTMs, topology, processing products such as chains and signal peptides, mutagenesis, and more) and natural variants plus InterPro domains with GO terms; a PDB entry mapping to several accessions uses the lowest author chain and lists the rest in
ambiguityAn isoform accession fails as
invalid_accession, naming the canonical one. An accession UniProt merged into another entry answers as its successor, with the merge named first innotice; a demerged or deleted one fails asinactive_accessionwith itsreplacementsEach requested class carries
featuresTotal,variantsTotal, ordomainsTotal(InterPro's own membership count); a page with more records setstruncatedand names the next offset innotice, and an InterPro walk that stops short of its count setstruncatedand says how many membershipsdomains_offsetcan reach. One 50 s budget covers every upstream request in a callFailures are typed as
missing_identifier,invalid_accession,accession_not_found,inactive_accession,no_uniprot_mapping, orchain_not_found
pdb://{entry_id} resource
entry_idis a PDB entry ID (e.g.4HHB); returnsapplication/jsonwith title, methods, resolution, organisms, ligands, andpolymerEntitiescarrying every chain in bothauthAsymIdsandlabelAsymIds, withchainCountSame data as
protein_get_structurewithsource: experimental, except that tool lists an entity's first 100 chains unlessall_chainsis set
af://{uniprot} resource
uniprotis a UniProt accession, an isoform accession (e.g.P04637-2), or an AlphaFold DB entry ID (e.g.AF-P69905-F1); returnsapplication/jsonwithmeanPlddt,confidenceBuckets,cifUrl/pdbUrl/bcifUrl, andmodelVersion, plus anoticewhen UniProt merged the accession into another entry (the successor's model answers)Failures are typed as
invalid_accession,no_model,accession_not_found, orinactive_accession(with its replacements)Same data as
protein_get_structurewithsource: predicted
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.
PDB / AlphaFold-specific:
Search, fetch, and comparison treat experimental (PDB) and predicted (AlphaFold DB, ModelArchive, 3D-Beacons providers) structures the same way
Keyless across RCSB, AlphaFold DB, 3D-Beacons, PDBe, UniProt, InterPro, and Foldseek
Collection analytics run on RCSB's facet engine and return bucket counts, not matching entries
Foldseek and alignment jobs poll for up to
PROTEIN_ASYNC_POLL_TIMEOUT_MS(default 30 s) or the call's 50 s upstream budget, whichever ends first, then hand back a resume handle (ticketId, per-pairuuid) instead of blockingChain namespaces stay separate:
authAsymIdsfeedprotein_get_annotationschain,labelAsymIdsfeedprotein_compare_structureschain
Agent-friendly output:
Provenance: every hit names its
source(experimental/predicted) and the engine or database behind it, andprotein_get_structureandprotein_get_annotationscarry anattributionblock (see Upstream data licensing)Graceful partial failure:
failed[]rows and per-pairstatuskeep one bad ID or pair from failing the requestPaging and advisories: paged tools return
totalCountandnextStart, astartpast the end is flagged innoticeseparately from zero matches, and every advisory joins into that onenotice
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-mcp-server": {
"type": "streamable-http",
"url": "https://protein.caseyjhand.com/mcp"
}
}
}Self-Hosted / Local
Add the following to your MCP client configuration file. No API key is needed.
{
"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/mcpPrerequisites
Bun v1.4.4 or higher (or Node.js v24+).
No accounts or API keys: every upstream is public.
Installation
Clone the repository:
git clone https://github.com/cyanheads/protein-mcp-server.gitNavigate into the directory:
cd protein-mcp-serverInstall dependencies:
bun installConfigure environment (optional):
cp .env.example .env
# every variable has a working defaultConfiguration
Every variable is optional.
Variable | Description | Default |
| Poll budget for an async alignment or Foldseek job before it returns |
|
| Max IDs per |
|
| Max structures per |
|
| Buckets per dimension for |
|
| Max concurrent upstream requests for per-ID and per-pair fan-out (1–16). |
|
| Transport: |
|
| HTTP server port. |
|
| HTTP session mode: |
|
| Authentication: |
|
| Log level (RFC 5424). |
|
| Enable OpenTelemetry. |
|
Each upstream's base URL can also be pointed at a mirror: RCSB_SEARCH_BASE_URL, RCSB_DATA_BASE_URL, RCSB_FILES_BASE_URL, RCSB_MODELS_BASE_URL, RCSB_ALIGNMENT_BASE_URL, BEACONS_BASE_URL, PDBE_API_BASE_URL, ALPHAFOLD_BASE_URL, MODELARCHIVE_BASE_URL, FOLDSEEK_BASE_URL, UNIPROT_BASE_URL, INTERPRO_BASE_URL. See .env.example for their defaults and 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:httpRun 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 protein-mcp-server .
docker run --rm -p 3010:3010 protein-mcp-serverThe 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
Directory | Purpose |
|
|
| Server-specific environment variable parsing and validation with Zod. |
| Tool definitions ( |
| Resource definitions ( |
| Upstream clients: |
| The published |
| Unit and integration tests mirroring |
Development guide
See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:
Handlers throw, framework catches — no
try/catchin tool logicUse
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storageExport new definitions from the barrels in
src/mcp-server/*/definitions/index.tsand register them in thecreateApp()arrays insrc/index.tsWrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
Upstream data licensing
Structure and annotation data comes from public databases, each under its own license. protein_get_structure and protein_get_annotations return an attribution block with the license, citation, and homepage of every source that contributed to that response. CC BY and CC BY-SA sources require attribution on redistribution; CC0 sources ask only for citation.
Source | Contributes to | License |
| CC0 1.0 Universal | |
| CC BY 4.0 | |
| CC BY 4.0 | |
| CC BY-SA 4.0 | |
| CC BY 4.0 | |
| CC BY 4.0 | |
| CC0 1.0 Universal | |
| CC BY 4.0 |
best_available models arrive through 3D-Beacons, so the block credits the provider that actually supplied the model; a provider with no curated entry gets a See provider terms fallback instead of a guessed license. InterPro and GO are credited separately, each only when it contributes. This table covers upstream data; the server's own code is licensed separately (see License).
Contributing
Issues are welcome. Run checks and tests before submitting:
bun run devcheck
bun run testLicense
Apache-2.0 — see LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
RCSB PDB MCP — experimentally determined macromolecular structures.
Agent-to-Agent (A2A) + Model Context Protocol (MCP) hub for peptides.
Agent-to-Agent (A2A) + Model Context Protocol (MCP) hub for peptides.
Model Context Protocol server for Studex tools, notifications, and profile integrations
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enhances language models with protein structure analysis capabilities, enabling detailed active site analysis and disease-related protein searches through established protein databases.220ISC
- AlicenseCqualityDmaintenanceA comprehensive Model Context Protocol (MCP) server providing advanced access to the UniProt protein database.2621MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server that provides access to the Protein Data Bank (PDB) - the worldwide repository of information about the 3D structures of proteins, nucleic acids, and complex assemblies.528MIT
- AlicenseBqualityDmaintenanceA comprehensive Model Context Protocol (MCP) server that provides access to the AlphaFold Protein Structure Database through a rich set of tools and resources for protein structure prediction analysis.1937MIT