RCSB PDB

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)

Searching is two steps: build a query with an rcsb_query_* tool, then execute it with rcsb_search_request. The builders are pure — they return a query document (readable JSON plus a digest) and touch no network, so nothing is searched until you call `rcsb_search_request`. rcsb_query_composer joins two or more documents with AND/OR, which is also how a single search mixes services (e.g. sequence similarity AND an organism filter).

Build

Run

Discover

Both attribute catalogs are generated from the live metadata schemas by scripts/generate_search_attributes.py. To search chemical-component attributes, find the path with rcsb_list_pdb_search_attributes(schema="chemical"), pass chemical_attributes=True to rcsb_query_attribute, and usually set return_type="mol_definition".

Nested attributes. An object can hold many annotations, many binding affinities, many citations. For attributes carrying a nested_group, the query shape selects the semantics: conditions built in one rcsb_query_attribute call, with nothing else in it, must hold on the same record; conditions in separate calls are matched independently against any record. Both are valid and mean different things — type=Kd with value<1 describes one measurement, while an InterPro id and a GO type are necessarily two different annotations.

Counting and faceting are output options on rcsb_search_request, not separate tools: every response includes total_count (the full match count — for "how many ..." run the search with limit=1 and read it), and passing facets returns a breakdown (terms/histogram/date_histogram/range/cardinality) instead of hits. A terms facet also tells you what your hits share, which is how a handful of results becomes a re-searchable value.

Grouping. group_by returns one representative per cluster — seqid_30 … seqid_95 for sequence-identity clusters, or uniprot to collapse by accession — with group_by_ranking choosing the representative. Requires return_type="polymer_entity"; the response reports group_count alongside total_count.

Sorting. sort_by (an attribute path) + sort_direction (asc/desc) replaces the default score ordering (for 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".

Paging. rcsb_search_request accepts limit (1–100, default 10) and offset (default 0), and each response reports total_count, has_more, and next_offset — call again with the same query document and offset=next_offset. For an explicit "ALL ..." request, all_hits=True returns the complete set in one call (refused above 10,000 hits, and it cannot be combined with 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.

Report

Install

RCSB hosts the server, so most clients need no install — point them at https://mcp-beta.rcsb.org/mcp (see Connect an agent). Install only to run it yourself, pin a version, or develop against it:

# run the published package without installing

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

`