rcsb-mcp

An MCP server for interrogating Protein Data Bank structures — discover, inspect, and cross-reference — from LLM clients (Claude Desktop, MCP Inspector, Cursor, etc.). It spans three RCSB APIs:

• Discover — find structures with the Search API (keyword, attribute, sequence, chemistry, 3D shape, motif).
• Inspect — fetch entry / entity / assembly / ligand details and annotations from the Data API.
• Relate — map sequences and positional features across PDB, UniProt, and NCBI with the Sequence Coordinates API.

Tools

Search (search.rcsb.org)

The two text tools (rcsb_search_fulltext, rcsb_search_by_attribute) also take group_by_identity (100/95/90/70/50/30) to return one representative per sequence-identity cluster — i.e. non-redundant results. To search chemical-component attributes, find the path with rcsb_list_pdb_search_attributes(schema="chemical"), then pass chemical=True to rcsb_search_by_attribute / rcsb_search_fulltext (usually with return_type="mol_definition"). Both catalogs (structure and chemical) are generated from the live metadata schemas by scripts/generate_search_attributes.py.

Counting and faceting are output options on every rcsb_search_* tool, not separate tools: each response includes total_count (the full match count — for "how many ..." run a search with limit=1 and read it), and passing facets returns a breakdown (terms/histogram/date_histogram/range/cardinality) instead of hits. The rcsb_search_by_* service tools (sequence, chemical, structure, seq/struc-motif) also take optional attributes filters, so e.g. a sequence search can be restricted to an organism in one call.

Sorting is likewise available on every rcsb_search_* tool via sort_by (an attribute path) + sort_direction (asc/desc), replacing the default score ordering (for the similarity searches this overrides the similarity-ranked order). Only attributes indexed for sorting work — those exposing exact_match (strings) or equals (numbers/dates) in rcsb_list_pdb_search_attributes; sorting is not available for return_type="mol_definition" (chemical-component results are ranked by score only).

Paging. Every search tool that returns hits accepts limit (1–100, default 10) and offset (default 0). Each response reports total_count, has_more, and next_offset; to fetch the next page, call the tool again with the same query and offset set to the returned next_offset.

Data (data.rcsb.org/graphql)

There is one tool per Data API GraphQL root field. Each takes a list of IDs (singular lookups = a one-element list) plus an optional fields argument to override the curated default selection with your own GraphQL sub-selection. Unknown IDs are reported under not_found. Discover the paths to put in fields with rcsb_describe_data_object — browse a level, drill into a nested object with into=, or search the schema by keyword with query= + max_depth=. Every path it returns is verified against the live schema, so don't guess field names.

The Search API only returns identifiers, so a search is the first step: batch the returned ids into the matching rcsb_get_* tool to fetch titles, organisms, and other metadata (these tools query the GraphQL endpoint, batching every requested ID into one request). All 16 typed tools are generated from a single registry in queries.py (DATA_OBJECTS), so adding a field or endpoint is a one-line change.

Sequence Coordinates (sequence-coordinates.rcsb.org/graphql)

Maps alignments and positional annotations between sequence reference systems (UNIPROT, NCBI_PROTEIN, NCBI_GENOME, PDB_ENTITY, PDB_INSTANCE). Each tool takes an optional fields argument to override the default selection; use rcsb_describe_seqcoord_object to discover what fields are available.

This is the only RCSB API that cross-references NCBI (RefSeq protein / genome) — the Data API only knows UniProt. So "what NCBI proteins map to a PDB structure?" is answered by rcsb_seqcoord_alignments, not the Data API. PDB query ids must be entity-level (4HHB_1), not a bare entry (4HHB); for a whole entry, query each polymer entity.

Install

# run the published package without installing (recommended for clients)
uvx rcsb-mcp
# or install it
pip install rcsb-mcp

rcsb-mcp is listed in the Official MCP Registry as io.github.rcsb/rcsb-mcp, so registry-aware clients can discover it directly.

For local development, install from the project root instead:

pip install -e .
# or with uv
uv pip install -e .

Run / test

# unit tests (no network)
hatch test          # or: python tests/test_queries.py

# run the server over stdio
python -m rcsb_mcp.server
# or, after install:
rcsb-mcp

# inspect interactively
npx @modelcontextprotocol/inspector python -m rcsb_mcp.server

There is also an end-to-end evaluation suite (evals/) — 10 read-only, stable questions that measure how well an LLM can drive these tools to answer real PDB questions. See evals/README.md to run it.

Connect to Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "rcsb-mcp": {
      "command": "uvx",
      "args": ["rcsb-mcp"]
    }
  }
}

For a local source checkout, point at the module instead:

{
  "mcpServers": {
    "rcsb-mcp": {
      "command": "python",
      "args": ["-m", "rcsb_mcp.server"],
      "cwd": "/absolute/path/to/rcsb-mcp/src"
    }
  }
}

Restart Claude Desktop. The tools appear under the connectors (plug) icon.

Example prompts

• "Find high-resolution human hemoglobin structures." → rcsb_search_fulltext (keyword + attributes)
• "Human hemoglobin structures better than 2 Å, best resolution first." → rcsb_search_fulltext (keyword + attributes, sort_by)
• "What PDB entries match this protein sequence: MTEY..." → rcsb_search_by_sequence
• "Find structures containing a ligand like this SMILES / with formula C8H9NO2." → rcsb_search_by_chemical
• "Which structures have a 3D fold similar to 4HHB?" → rcsb_search_by_structure
• "Find proteins with a zinc-finger motif." → rcsb_search_by_seqmotif
• "Structures of proteins with kinase activity / involved in DNA repair / in the mitochondrial membrane." → rcsb_find_go_terms → rcsb_search_by_attribute on rcsb_polymer_entity_annotation.annotation_lineage.id
• "Structures containing an SH2 domain / immunoglobulin fold." → rcsb_find_interpro_domains → rcsb_search_by_attribute on rcsb_polymer_entity_annotation.annotation_id
• "Alcohol dehydrogenase structures / any EC 3.4.21 serine protease." → rcsb_find_enzyme_classes → rcsb_search_by_attribute on rcsb_polymer_entity.rcsb_ec_lineage.id
• "Structures of proteins associated with cystic fibrosis / breast cancer." → rcsb_find_disease_terms → rcsb_search_by_attribute on rcsb_uniprot_annotation.annotation_lineage.id
• "Structures from mammals / from a particular organism or clade." → rcsb_find_organisms → rcsb_search_by_attribute on rcsb_entity_source_organism.taxonomy_lineage.id
• "Non-redundant human kinase structures (90% identity clusters)." → rcsb_search_fulltext with group_by_identity=90
• "How many human X-ray structures are there?" → rcsb_search_by_attribute (read total_count)
• "Break down ribosome structures by experimental method / by release year." → rcsb_search_fulltext with facets
• "Find structures with the same catalytic-site geometry as residues 162/193/219 of 2MNR." → rcsb_search_strucmotif
• "Find chemical components under 150 Da." → rcsb_list_pdb_search_attributes(schema="chemical") + rcsb_search_by_attribute with chemical=True
• "Summarize PDB entries 4HHB, 1MBN and 6VXX." → rcsb_get_entries
• "What's the sequence and organism of entity 4HHB_1?" → rcsb_get_polymer_entities
• "Tell me about the ligand HEM." → rcsb_get_chem_comps
• "What's the composition of the 4HHB biological assembly?" → rcsb_get_assemblies
• "Which PDB entries does P69905 map to?" → rcsb_get_uniprot
• "Which PDB entities align to UniProt P69905, and over what ranges?" → rcsb_seqcoord_alignments
• "What NCBI proteins map to 4HHB?" → rcsb_seqcoord_alignments per entity (4HHB_1, 4HHB_2), to_ref=NCBI_PROTEIN
• "Show UniProt features mapped onto PDB entity 4HHB_1." → rcsb_seqcoord_annotations
• "Pull a field the compact defaults don't include." → rcsb_describe_data_object to find the path, then the matching rcsb_get_* tool with fields=

Report output (RCSB_MCP_REPORT_BASE_URL)

rcsb_render_report returns a self-contained link, not the markup — so the agent never has to reproduce the ~20 KB document (the single most expensive step of a report turn). The whole report is gzip+base64url-packed into the URL, so the server stores nothing and any replica renders any link on demand.

Set RCSB_MCP_REPORT_BASE_URL to the origin that serves this MCP (e.g. https://rcsb-mcp.rcsb.org) and the tool returns { url: "<base>/r?d=<packed report>", html: null }. The agent hands the user that link; opening it hits the stateless render endpoint:

GET /r?d=<gzip+base64url of the report JSON>   →   text/html

The endpoint decodes, validates against the report schema, and renders with the fixed template. It is hardened for a public route: the d token and its decompressed size are both capped (a gzip bomb is refused before it expands), the page carries Content-Security-Policy: default-src 'none' + noindex, and every value is escaped by the template — a crafted link can only ever produce an escaped report.

Fallback. When RCSB_MCP_REPORT_BASE_URL is unset (e.g. local stdio dev with no reachable endpoint) or a report is too large to pack into a URL, the tool returns html instead of url, and the rcsb_search_assistant prompt tells the model to write it to a .html file. Reports compress to ~1 KB even at 50 rows, so the size fallback is rare.

Notes

• Search endpoint: https://search.rcsb.org/rcsbsearch/v2/query (POST, JSON body).
• Data endpoint: https://data.rcsb.org/graphql (POST, GraphQL). It returns HTTP 200 even for query errors, reporting them in an errors array.
• Sequence Coordinates endpoint: https://sequence-coordinates.rcsb.org/graphql (POST, GraphQL; same HTTP-200-with-errors behavior).
• The rcsb_find_* resolvers map free text to ontology ids via EBI services — the non-RCSB dependencies: GO via QuickGO (.../QuickGO/services/ontology/go/search), InterPro (.../interpro/api/entry/interpro/), EC via EBI Search/IntEnz (.../ebisearch/ws/rest/intenz), and disease via OLS/MONDO (.../ols4/api/search?ontology=mondo). The resolved ids then drive RCSB annotation searches (rcsb_polymer_entity_annotation.*, rcsb_polymer_entity.rcsb_ec_lineage.id, rcsb_uniprot_annotation.annotation_lineage.id).
• No API key required; the APIs are public. Be considerate with request volume.
• A full list of searchable attributes for rcsb_search_by_attribute is in the Search API attribute reference; the Data API schema is documented at data.rcsb.org/index.html#gql-api.

Prompt

The server also exposes an MCP prompt, rcsb_search_assistant ("RCSB PDB search assistant") — the full tool-routing guide, followed by the search requirements and the HTML-report output format. Because it is served over the protocol's prompts capability, any MCP client can list and invoke it (e.g. Claude Desktop surfaces server prompts in the + / prompt menu); there's nothing to copy-paste. The policy half lives in src/rcsb_mcp/prompts/rcsb_search_assistant.md and the guide half is rcsb_mcp_guide.md, joined at request time so the two never drift; both ship with the package.

Invoke it when you want answers formatted as a PDB report. It is self-sufficient: the appended guide is the same text as the always-on server instructions, so the prompt still works on clients that never inject those — and the tool descriptions' "see the server instructions" cross-references resolve against it. A second prompt, rcsb_mcp_guide, serves that guide on its own for sessions that want the routing guidance without the report policy; load one or the other, not both.