Protein Mcp Server

cyanheads/protein-mcp-server

Connects Claude directly to RCSB PDB, PDBe, and UniProt for querying and analyzing protein structures. Exposes six tools for searching structures by keyword or filter, retrieving full structural data in mmCIF or PDB format, finding similar proteins via sequence or structure alignment, tracking ligands across the database, comparing multiple structures with RMSD calculations, and running statistical analyses across the entire PDB. Built on TypeScript with pluggable storage backends and OpenTelemetry instrumentation. Reach for this when you need Claude to answer questions about protein folds, binding sites, or experimental methods without manually parsing PDB files or writing custom API calls.

GitHub stars: 6
tools: 7
transport: STDIO, HTTP
env vars: 6
last updated: Nov 4, 2026

View on GitHub

Install

From registry metadata

$ npx add-mcp https://protein.caseyjhand.com/mcp --name protein

Run in your terminal. add-mcp asks which agents to add it to (Claude Code, Codex, Cursor and more). Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

$ claude mcp add --transport http protein https://protein.caseyjhand.com/mcp

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 7 tools

Verified live against the running server on Nov 6, 2026.

protein_search_structuresSearch experimental (PDB) and predicted (computed-model) protein structures by free text, protein sequence (triggers an mmseqs2 similarity search), and/or organism, method, resolution, and bound-ligand filters. Returns ranked hits; the experimental page is enriched with title,...12 params

Search experimental (PDB) and predicted (computed-model) protein structures by free text, protein sequence (triggers an mmseqs2 similarity search), and/or organism, method, resolution, and bound-ligand filters. Returns ranked hits; the experimental page is enriched with title,...

Parameters* required

content_typestring

Which structure universe to search: experimental (PDB), predicted (computed models), or all.one of experimental · predicted · alldefault: all

facetsarray

Optional dimensions to summarize as a facet breakdown alongside the hits. Each dimension at most once; repeating one is rejected.

ligandstring

Filter by bound ligand: an exact chemical component ID (e.g. "STI" for imatinib, "HEM"), in any letter case. Keeps structures holding the component as a bound (non-polymer) copy, not as a residue i...

limitinteger

Maximum hits to return (1–100).default: 25

max_evaluenumber

Maximum E-value for a sequence search. Requires sequence — supplying it without one is rejected, since the threshold filters only a sequence search. Default 1.

max_resolutionnumber

Maximum resolution in Å (lower is sharper); applies to experimental structures.

methodstring

Filter by experimental method: X-RAY DIFFRACTION, ELECTRON MICROSCOPY, SOLUTION NMR, SOLID-STATE NMR, ELECTRON CRYSTALLOGRAPHY, NEUTRON DIFFRACTION, FIBER DIFFRACTION, POWDER DIFFRACTION, SOLUTION...

min_identitynumber

Minimum sequence identity (0–1) for a sequence search. Requires sequence — supplying it without one is rejected, since the threshold filters only a sequence search. Default 0.

organismstring

Filter by source organism: a scientific name ("Homo sapiens"), an NCBI common name ("human", "E. coli"), or an NCBI taxon ID ("9606"), in any letter case. Matches that taxon and every taxon under i...

querystring

Free-text query (protein name, gene, keyword, PDB title terms).

sequencestring

Protein sequence for RCSB mmseqs2: at least 10 residues in A–I or K–Z (J excluded; B/O/U/X/Z accepted). Whitespace is removed and ASCII lowercase normalized.

startinteger

Zero-based result offset. Combine with limit to retrieve later pages.default: 0

protein_get_structureFetch structures with metadata and coordinate-file URLs. source "experimental" takes PDB entry IDs, and also resolves the computed-model IDs protein_search_structures returns (AF_*/MA_*), which come back marked source "predicted" with their modelling provider; "predicted" take...5 params

Fetch structures with metadata and coordinate-file URLs. source "experimental" takes PDB entry IDs, and also resolves the computed-model IDs protein_search_structures returns (AF_*/MA_*), which come back marked source "predicted" with their modelling provider; "predicted" take...

Parameters* required

coords_offsetinteger

Character offset of the window to return when exactly one structure is selected (sections naming one ID, or include_coords on a one-ID call): the window is characters [coords_offset, coords_offset...default: 0

ids*array

PDB entry IDs or computed-model IDs such as AF_AFP69905F1 (source experimental); UniProt accessions, isoform accessions such as P04637-2, or AlphaFold DB entry IDs such as AF-P04637-2-F1 (predicted...

include_coordsboolean

Inline coordinate text for every resolved structure — mmCIF, or PDB format when no mmCIF URL is available; coordinateFormat names which. A lone file arrives in 24000-character windows. Off by defau...default: false

sectionsarray

Structure IDs to inline coordinates for, in place of include_coords — from an overflow outline, or one ID to page through its file with coords_offset. Each must match the id of a structure this cal...

sourcestring

Where to fetch: experimental (PDB), predicted (AlphaFold), or best_available (federated pick).one of experimental · predicted · best_availabledefault: experimental

protein_find_similarFind structurally or evolutionarily related proteins. by:"sequence" runs an RCSB mmseqs2 sequence-similarity search (synchronous; experimental PDB entries only — protein_search_structures with a sequence also reaches computed models) over a sequence — supplied directly, taken...12 params

Find structurally or evolutionarily related proteins. by:"sequence" runs an RCSB mmseqs2 sequence-similarity search (synchronous; experimental PDB entries only — protein_search_structures with a sequence also reaches computed models) over a sequence — supplied directly, taken...

Parameters* required

by*string

Similarity axis: sequence (mmseqs2) or structure (Foldseek).one of sequence · structure

chainstring

Author chain ID (auth_asym_id, case-sensitive) of pdb_id selecting the protein entity whose sequence by:"sequence" searches, e.g. "B" for the beta chain of 4HHB. Requires pdb_id. Default: the lowes...

databasesarray

Foldseek target databases (by:structure), by exact name. Default pdb100 + afdb50. pdb100: experimental PDB entries; afdb50, afdb-swissprot, afdb-proteome: AlphaFold DB models; cath50: CATH domains...

limitinteger

Maximum hits to return (1–100).default: 25

max_evaluenumber

Maximum E-value (by:sequence). Default 1.

min_identitynumber

Minimum sequence identity 0–1 (by:sequence). Default 0.

pdb_idstring

PDB entry ID to derive the query from. by:"sequence" searches one of its protein entities (see chain); by:"structure" uploads its mmCIF file, up to 16,000,000 characters.

queryinteger

Zero-based Foldseek query index (by:structure). Default 0. Foldseek splits a multichain structure into one query per chain, in file order; queryCount in the response says how many the job holds. Pa...

sequencestring

Protein sequence for by:sequence: at least 10 residues in A–I or K–Z (J excluded; B/O/U/X/Z accepted). Whitespace is removed and ASCII lowercase normalized.

startinteger

Zero-based result offset. Pages a by:sequence search, and a completed by:structure job when re-called with its ticket_id.default: 0

ticket_idstring

Foldseek ticket ID from a prior by:structure response whose status was "computing". When set, polls that existing job instead of submitting a new search (by:structure only) — pdb_id/uniprot/databas...

uniprotstring

UniProt identifier to derive the query from: a canonical accession (e.g. P69905), an isoform accession (e.g. P04637-2), or a UniProtKB entry name (e.g. HBA_HUMAN), which resolves to its entry’s acc...

protein_track_ligandsLigand discovery and binding-site analysis across the PDB. mode "find_ligand" resolves a name or formula to chemical component IDs with metadata (formula, weight, SMILES), ranked by deposition frequency — most-deposited component first, so the top hit is the most common match...6 params

Ligand discovery and binding-site analysis across the PDB. mode "find_ligand" resolves a name or formula to chemical component IDs with metadata (formula, weight, SMILES), ranked by deposition frequency — most-deposited component first, so the top hit is the most common match...

Parameters* required

comp_idstring

Exact chemical component ID (modes structures_with_ligand and binding_site).

limitinteger

Maximum results to return (1–100).default: 25

mode*string

Operation: resolve a ligand, find structures containing it, or analyze its binding site.one of find_ligand · structures_with_ligand · binding_site

pdb_idstring

PDB entry ID (mode binding_site).

querystring

Ligand name or formula (mode find_ligand).

startinteger

Zero-based result offset (modes structures_with_ligand and binding_site; binding_site pages ligand instances).default: 0

protein_compare_structuresStructurally align multiple structures (up to the configured batch cap; structures past it are returned in ignored) via the RCSB Structural Comparison service (TM-align / jFATCAT). reference:"first" aligns every structure to the first; reference:"all_pairs" computes the full p...5 params

Structurally align multiple structures (up to the configured batch cap; structures past it are returned in ignored) via the RCSB Structural Comparison service (TM-align / jFATCAT). reference:"first" aligns every structure to the first; reference:"all_pairs" computes the full p...

Parameters* required

methodstring

Alignment algorithm: tm-align, fatcat-rigid, or fatcat-flexible.one of tm-align · fatcat-rigid · fatcat-flexibledefault: tm-align

referencestring

Align all to the first structure, or compute the full pairwise matrix.one of first · all_pairsdefault: first

resumearray

Resume tickets from a prior call: for each pair whose labels match an entry here, poll the existing UUID instead of submitting a new alignment job. Copy a, b, and uuid verbatim from a prior respons...

structures*array

The structures to compare, up to the configured batch cap; structures past it are returned in ignored and not compared. A structure repeated here is compared once.

timeout_sinteger

Poll budget per pair in seconds before returning "computing". Defaults to the server setting.

protein_analyze_collectionProfile the PDB into distributions and trends over an optional scoping query: counts by method, organism, or polymer composition; resolution and molecular-weight histograms; release-year timelines; and multidimensional cross-tabs (e.g. method × release_year). Aggregation runs...8 params

Profile the PDB into distributions and trends over an optional scoping query: counts by method, organism, or polymer composition; resolution and molecular-weight histograms; release-year timelines; and multidimensional cross-tabs (e.g. method × release_year). Aggregation runs...

Parameters* required

bucket_limitinteger

Max buckets per dimension level, not per response. A cross-tab applies the cap separately to the parent dimension and to the nested child inside each parent bucket, so up to bucket_limit × (1 + buc...

content_typestring

Which structure universe to profile. Default experimental. Computed models carry no experimental metadata, so method and resolution return nothing under "predicted".one of experimental · predicted · alldefault: experimental

group_by*array

1 dimension for a breakdown, or 2 distinct dimensions for a cross-tab (the first nests the second). Repeating a dimension is rejected.

intervalvalue

Bin width for a histogram dimension (a number, for resolution or molecular_weight) or period for a date histogram ("year", for release_year). Applies to whichever requested group_by dimension can c...

max_resolutionnumber

Optional maximum-resolution scope (Å).

methodstring

Optional experimental-method scope: X-RAY DIFFRACTION, ELECTRON MICROSCOPY, SOLUTION NMR, SOLID-STATE NMR, ELECTRON CRYSTALLOGRAPHY, NEUTRON DIFFRACTION, FIBER DIFFRACTION, POWDER DIFFRACTION, SOLU...

organismstring

Optional source-organism scope: a scientific name ("Homo sapiens"), an NCBI common name ("human"), or an NCBI taxon ID ("9606"), in any letter case. Matches that taxon and every taxon under it; a m...

querystring

Optional free-text scope (e.g. "kinase"); omit to profile the whole PDB.

protein_get_annotationsSequence and functional annotation for a protein: UniProt positional features (domains, binding and active sites, PTMs including cross-links and lipidation, topology, DNA binding, processing products such as chains and signal peptides, mutagenesis), natural variants, and Inter...8 params

Sequence and functional annotation for a protein: UniProt positional features (domains, binding and active sites, PTMs including cross-links and lipidation, topology, DNA binding, processing products such as chains and signal peptides, mutagenesis), natural variants, and Inter...

Parameters* required

chainstring

Author chain ID (auth_asym_id, e.g. "A") that disambiguates a multi-chain PDB entry to a specific UniProt accession. Case-sensitive — must match the author chain ID exactly (large structures can ca...

domains_offsetinteger

Zero-based offset into InterPro memberships; independent of features and variants.default: 0

features_offsetinteger

Zero-based offset into functional features; independent of variants and domains.default: 0

includestring

Which annotation classes to fetch: features, domains (InterPro), variants, or all.one of features · domains · variants · alldefault: all

limitinteger

Per-class page size (1–200, default 50). Continue each class independently with features_offset, variants_offset, or domains_offset; the notice gives the next offset.default: 50

pdb_idstring

PDB entry ID; resolved to a UniProt accession via cross-reference.

uniprotstring

Canonical UniProt accession (e.g. P69905). Isoform accessions (e.g. P04637-2) are rejected; UniProt annotates the canonical entry. Takes precedence over pdb_id.

variants_offsetinteger

Zero-based offset into natural variants; independent of features and domains.default: 0

Configuration

MCP_LOG_LEVELdefault: info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault: http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault: 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault: 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault: /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault: none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Readme

@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

View the full README on GitHub

Details

Repository: github.com/cyanheads/protein-mcp-server
Package: @cyanheads/protein-mcp-server
Transport: STDIO, HTTP
Registry: MCP registry, active
Resources: 1
Tools verified: Nov 6, 2026

Protein Mcp Server

Install

Tools

Configuration

Readme

@cyanheads/protein-mcp-server

Details

More from cyanheads