Official

Protein Structure Research Stack

Combine RCSB structure records with UniProt protein annotations, inspect method/resolution and entity mappings, and download a traceable mmCIF file.

Level: Intermediate Cost: Mixed Privacy: Cloud ~45 min

Start Setup

Public link：https://chemaiatlas.com/recipes/protein-structure-research/

You'll be able to

Retrieve PDB method, resolution and polymer records.
Cross-check UniProt accessions and download mmCIF.

What you'll build

Scope and environments

Use Claude Desktop, Node.js >=24 for UniProt MCP 0.2.4, and an independent Python >=3.13 environment for RCSB MCP 0.1.0 at commit df04c993c31f43d69d6273737bda2de39ace0850. Do not reuse the Python 3.11 RDKit environment. RCSB runs server.py in stdio; its upstream project dependencies are ranges, so record all resolved versions. No database API key is required for this reference retrieval. Both APIs and Claude use external network services.

Interpretation

A polymer entity is not the same as a chain or a biological assembly. A deposited structure may omit residues and contain constructs or mutations. Compare method, resolution, mapped entities and the original validation report. Structural metadata alone does not demonstrate docking, binding or clinical performance. Downloads can overwrite matching filenames; choose a new output directory.

The pinned RCSB helper writes progress and errors with print on stdout. Save and use the supplied recipe_rcsb_server.py adapter to route only that module's prints to stderr and preserve the MCP transport.

Protein annotation retrieval

UniProt MCP (cyanheads)

Structure metadata and download tools

RCSB MCP (cnyambura)

PDB structure metadata source

RCSB PDB Data API

Stack Components

UniProt MCP (cyanheads)

Protein annotation retrieval · 0.2.4

Node 24+; separate from the Python server.

See upstream licenses and client/service account terms.

View Resource

RCSB MCP (cnyambura)

Structure metadata and download tools · 0.1.0; df04c993c31f43d69d6273737bda2de39ace0850

Requires Python >=3.13; use a separate environment and record resolved dependency versions.

See upstream licenses and client/service account terms.

View Resource

RCSB PDB Data API

PDB structure metadata source · RCSB Data API / live

Record PDB ID, retrieval date and entry version if provided.

See upstream licenses and client/service account terms.

View Resource

Compatibility

Client	OS	Architecture	Version requirements
Claude Desktop	macOS	Any	See component requirements
Claude Desktop	Windows	Any	See component requirements
Python	macOS	Any	>= 3.13
Python	Windows	Any	>= 3.13
Python	Linux	Any	>= 3.13

Setup & Test

1. Prepare Node.js and Claude Desktop

All platforms

Install Node.js 24 or newer with npm and Claude Desktop. Confirm that local MCP is allowed and HTTPS access to the target database is available. Bun is not needed for this Node-based variant.

node --version
npm --version

Official source

Expected result

Node reports v24 or newer; npm is available.

2. Install the pinned MCP package locally

All platforms

Use a new writable working directory. This installs the server in .mcp-packages, rather than globally; keep its lockfile for verification. The upstream npx entry and the local dist/index.js entry use the same published package.

npm install --prefix .mcp-packages @cyanheads/[email protected]
npm ls --prefix .mcp-packages --depth=0

Official source

Expected result

The requested exact package version is installed.

3. Prepare an isolated Python 3.13 environment

All platforms

Install Git and Python 3.13. The RCSB project declares Python >=3.13; check wheel availability for the selected architecture.

Official source

Expected result

Python 3.13 is available without changing other recipe environments.

4. Install RCSB MCP on macOS

macOS

Clone to a new working directory and install the pinned checkout.

git clone https://github.com/cnyambura/rcsb-mcp.git
cd rcsb-mcp
git checkout df04c993c31f43d69d6273737bda2de39ace0850
python3.13 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -m pip freeze

Official source

Expected result

Installation completes and resolved versions are recorded.

5. Install RCSB MCP on Windows

Windows

Use PowerShell; invoke the virtual environment directly.

git clone https://github.com/cnyambura/rcsb-mcp.git
cd rcsb-mcp
git checkout df04c993c31f43d69d6273737bda2de39ace0850
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m pip freeze

Official source

Expected result

Installation completes and resolved versions are recorded.

6. Save the stdio output adapter

All platforms

Save as recipe_rcsb_server.py beside the upstream server.py. It does not modify upstream source or redirect the global stdout stream.

"""Keep the upstream RCSB API's progress/error prints off MCP stdout.

Save beside server.py and rcsb_api.py in the pinned RCSB checkout.
Source: https://github.com/cnyambura/rcsb-mcp/blob/df04c993c31f43d69d6273737bda2de39ace0850/rcsb_api.py
Source-reviewed example; not executed.
"""
import functools
import sys

import rcsb_api
import server

# Only change print lookup in this module; preserve the process stdout stream.
rcsb_api.print = functools.partial(print, file=sys.stderr)

if __name__ == "__main__":
    server.mcp.run()

Official source

Expected result

The adapter is present beside the upstream modules; client config launches it.

7. Configure both servers on macOS

macOS

Merge both entries into Claude Desktop mcpServers and replace absolute-path placeholders. RCSB uses the separate Python 3.13 environment and server.py stdio entry; UniProt uses Node 24+. Prepare a new writable directory for structure downloads; do not choose an existing research-data directory. Launch recipe_rcsb_server.py rather than the raw server.py entry.

{
  "mcpServers": {
    "uniprot": {
      "command": "/ABSOLUTE/PATH/TO/node",
      "args": [
        "/ABSOLUTE/PATH/.mcp-packages/node_modules/@cyanheads/uniprot-mcp-server/dist/index.js"
      ],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    },
    "rcsb-pdb": {
      "command": "/ABSOLUTE/PATH/rcsb-mcp/.venv/bin/python",
      "args": [
        "/ABSOLUTE/PATH/rcsb-mcp/recipe_rcsb_server.py"
      ]
    }
  }
}

Official source

Expected result

Both entries point to their respective installed runtime and server files.

8. Configure both servers on Windows

Windows

{
  "mcpServers": {
    "uniprot": {
      "command": "C:\\ABSOLUTE\\PATH\\TO\\node.exe",
      "args": [
        "C:\\ABSOLUTE\\PATH\\.mcp-packages\\node_modules\\@cyanheads\\uniprot-mcp-server\\dist\\index.js"
      ],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    },
    "rcsb-pdb": {
      "command": "C:\\ABSOLUTE\\PATH\\rcsb-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\ABSOLUTE\\PATH\\rcsb-mcp\\recipe_rcsb_server.py"
      ]
    }
  }
}

Official source

Expected result

Both entries point to their respective installed runtime and server files.

9. Inspect both connectors

All platforms

Completely restart Claude and verify uniprot_get_entry, get_pdb_entry, get_polymer_entity and download_structure_file.

Official source

Expected result

Both connectors are connected.

10. Inspect and download 4HHB

All platforms

Use a new absolute download directory, approve the requested destination, and verify the saved file exists.

Use get_pdb_entry with pdb_id="4HHB" and get_polymer_entity for entity_id="1" and "2". Report the experimental method, resolution, polymer entities and chain mapping. Use returned UniProt cross-references to retrieve the matching records with uniprot_get_entry. Finally, after I specify a new absolute output directory, call download_structure_file for 4HHB in cif format. Report the returned path, source links and retrieval date. Do not infer ligand affinity or docking performance from the structure.

Official source

Expected result

Reference 4HHB: human deoxyhemoglobin, X-ray diffraction, 1.74 Å; entity 1 maps to alpha/P69905 and entity 2 to beta/P68871. Compare actual results with https://www.rcsb.org/structure/4HHB . A successful download returns a real path to nonempty mmCIF data; do not accept only a generated filename.

Troubleshooting

Startup failure: check Node 24+, the absolute node/module paths, JSON syntax and the local install lockfile.
Tools missing: restart the desktop client and inspect Developer logs.
HTTP 429 or timeout: reduce request volume, use pagination and retry with backoff; preserve partial results.
Missing database fields: show them as unavailable, not inferred values.
Python installation rejected: use Python 3.13+, not the RDKit 3.11 environment.
Download fails: check output directory permissions and available space; preserve the tool error.
stdout protocol error: inspect upstream RCSB logging/error output; do not record a broken stdio session as successful.
Mapping mismatch: use entity-specific accessions; chain IDs and entity IDs are distinct.
Resolution missing: report the experimental method and unavailable value, not a guessed resolution.

Still not working

Alternatives

Retrieve the same record via the RCSB website and its direct Data API; use the web validation report and Mol* viewer for inspection. UniProt alone cannot replace experimental structure records.