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"). The chemical catalog is generated from the live metadata schema by scripts/generate_chemical_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.

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_list_data_fields (flat keyword search) or rcsb_describe_data_object (level-by-level) — every path they return 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 GraphQL doesn't expose by default / combine objects." → rcsb_data_graphql

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, pdb_assistant ("PDB structure assistant") — the runtime assistant persona plus 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 text lives in src/rcsb_mcp/prompts/pdb_assistant.md and ships with the package.

This is deliberately separate from the always-on server instructions (tool routing/chaining guidance): the prompt is opt-in application/presentation policy, so invoke it when you want answers formatted as a PDB report.