Protein MCP Server

@cyanheads/protein-mcp-server Federated protein structure & annotation across experimental (PDB) and predicted (AlphaFold) models via MCP. STDIO or Streamable HTTP. 7 Tools • 2 Resources

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

Resources

Both resources are also reachable through protein_get_structure, for clients that don't surface resources.

Skills

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.

Capability reference

protein_search_structures tool

• At least one of query, sequence (an mmseqs2 search; min_identity / max_evalue apply only with it), organism, method, max_resolution, or ligand (an exact component ID held as a bound copy); content_type is experimental, predicted, or all (default); up to 100 hits per page (default 25) via limit / start
• organism takes 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. method takes one of the 13 RCSB experimental methods in any letter case, or an alias (cryo-EM, cryoEM, EM, X-ray, xray, NMR for both NMR methods); anything else fails as unknown_method
• A sequence needs at least 10 residues; whitespace is stripped and case normalized, and an invalid one fails as invalid_sequence. Each hit names its source and an entry id you can pass to other tools, and carries organisms (a sequence hit's are the matched entity's). Sequence hits add identity, evalue, bitscore, and the aligned ranges, with queryLength at the response level
• Optional facets (method, organism, polymer_type, resolution, release_year, molecular_weight) add a breakdown capped at PROTEIN_FACET_BUCKET_CAP buckets per dimension; 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 the AF_* / MA_* computed-model IDs search returns (these come back as source: predicted); predicted takes UniProt accessions, isoform accessions (P04637-2), or AlphaFold DB entry IDs (AF-P04637-2-F1) for AlphaFold models with pLDDT/PAE; best_available takes the same identifiers (an entry ID reduces to its accession) and returns the PDB entry with the widest UniProt coverage (ties to the finest resolution), else the model with the highest confidence on the lDDT scale. Best-available records carry coverage, uniprotStart, and uniprotEnd; a pick can come from a non-PDB provider, and only a record with pdbId is a PDB entry. If the PDB check is unavailable, the pick ranks the federated models alone and notice says so
• A UniProt accession merged into another entry resolves to its successor's model with a notice; a demerged or deleted one lands in failed[] with its replacements
• IDs are trimmed and de-duplicated (case-insensitive); up to PROTEIN_MAX_BATCH_IDS are looked up per call (default 25) and the remainder comes back in ignored. One 50 s budget covers all upstream lookups in a call; under predicted and best_available, an ID it stops, or whose upstream lookup fails (an error status, an HTML page, a network failure), lands in failed[] with a reason to re-call it
• Unresolved IDs land in failed[]; when nothing resolves the call fails as upstream_unavailable (retryable, with data.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 as all_failed (with data.failed); it fails mixed_id_types when the IDs don't fit source. Records include coordinateUrls for the files that exist, and organisms under experimental and predicted
• include_coords inlines coordinate text in 24,000-character windows: a single selected structure pages with coords_offset, passing back coordinatesNextOffset until it is absent; several selected files inline whole only when together they fit one window, otherwise an overflow outline lists each file's length to re-call with sections: [id]. coords_offset above 0 needs exactly one selected structure (coords_offset_needs_one_structure)

protein_find_similar tool

• by: sequence runs a synchronous RCSB mmseqs2 search over experimental PDB entries only (protein_search_structures with a sequence also reaches computed models) from sequence, pdb_id, or uniprot, filtered by max_evalue / min_identity; by: structure runs an async Foldseek search from pdb_id (its mmCIF file) or uniprot (its AlphaFold DB model) against pdb100 + afdb50 unless databases says otherwise. uniprot takes a canonical or isoform accession, or a UniProtKB entry name such as HBA_HUMAN (resolved to its entry's accession), in both modes and is shape-checked before any request (invalid_accession). databases takes 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 as databases_rejected. A field only the other mode reads fails as mode_mismatched_field; up to 100 hits per page (default 25)
• Sequences follow the same rules as protein_search_structures, and a direct sequence wins over identifiers. A pdb_id sequence query searches one protein entity: the one holding chain (author chain, case-sensitive, by: sequence only, requires pdb_id), else the lowest-numbered protein entity of at least 10 residues; DNA and RNA entities are never searched. The response names it in queryEntityId, and a notice lists the entry's other protein entities. An unmatched chain fails as chain_not_found, and chain without pdb_id as chain_without_pdb_id
• Hits name their source (and database for structure hits), ranked by score; sequence hits add identity, evalue, bitscore, and the aligned ranges. Responses report totalCount, nextStart, and queryLength
• A merged uniprot accession answers for its successor with a notice; a demerged or deleted one fails as inactive_accession with its replacements. A by: structure coordinate file is limited to 16,000,000 characters, and a larger one fails as structure_too_large
• A structure hit carries Foldseek's target name and an id only when the target resolves to a PDB entry or UniProt accession; bfvd_v3, mgnify_esm30, gmgcl_id, and bfmd hits have none. Other structure-hit fields: chain (a -N suffix marks a symmetry copy), title, probability, organisms / taxId (the target's, where Foldseek classifies it), and the aligned spans queryStart, queryEnd, targetStart, targetEnd, targetLength. A sequence hit's organisms are the matched entity's
• A structure job still running at the poll budget returns status: computing with a ticketId; re-call with ticket_id 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 via query (0-based, default 0) out of queryCount

protein_track_ligands tool

• mode is find_ligand (query: a name or formula), structures_with_ligand (comp_id), or binding_site (pdb_id, optional comp_id); a missing mode input fails as missing_param. limit is 1–100 (default 25), and start pages the last two modes
• find_ligand returns component IDs with formula, weight, SMILES, and InChIKey, ranked by depositionCount, with totalCount and candidatesConsidered showing when the candidate pool was cut short; structures_with_ligand lists entries highest resolution first, each with title, method, and hostEntities (the polymer entities whose chains the depositor assigned the ligand to)
• Matching counts bound non-polymer copies only, not a residue inside a polymer chain or a sugar inside a branched glycan; depositionCount equals the totalCount of structures_with_ligand for the same component
• binding_site returns pocket