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