RCSB PDB MCP Server: 3D Structures and Data

Overview

The RCSB PDB MCP Server provides a Model Context Protocol (MCP) implementation that bundles RCSB Protein Data Bank (PDB) assets into machine-consumable resources. It exposes protein 3D structures, experimental files (structure factors, electron density maps), validation reports, and related annotation in a consistent JSON resource format so downstream agents and large language models can request and ingest structural context on demand.

This server is useful for developers building retrieval-augmented workflows, automated structural analysis pipelines, or LLM integrations that need authoritative structural biology files and metadata. By packaging PDB artifacts as MCP-compatible resources, the server simplifies discovery, resolution, and streaming of structure-related data without having to manually traverse heterogeneous RCSB endpoints or file formats.

Features

• MCP-compatible endpoints that deliver structured model context for PDB entries
• Resource bundling of structure files (mmCIF/PDB), maps, structure factors, and validation reports
• Metadata-rich responses (experimental method, resolution, authors, release date)
• Support for direct file download URLs and optional streaming/proxying
• Caching and configurable TTL for backend requests to RCSB APIs
• Lightweight, container-friendly implementation suitable for local or cloud deployment
• CORS enabled for browser-based integrations and simple auth support for private deployments

Installation / Configuration

Clone the repository and run locally with Node.js, or build a Docker image.

Example: clone + Node (recommended for development)

git clone https://github.com/QuentinCody/rcsb-pdb-mcp-server.git
cd rcsb-pdb-mcp-server
npm install
# Create .env or export environment variables (examples below)
npm start

Example: build and run with Docker

docker build -t rcsb-pdb-mcp-server .
docker run -p 8080:8080 \
  -e PORT=8080 \
  -e CACHE_TTL=3600 \
  rcsb-pdb-mcp-server

Typical environment variables

PORT=8080                # server listen port
CACHE_TTL=3600           # seconds to cache backend responses
RCSB_API_BASE=https://data.rcsb.org
ENABLE_CORS=true
LOG_LEVEL=info

Notes:

• Configure TLS/HTTPS via a reverse proxy (nginx, Traefik) in production.
• The server uses the RCSB public APIs; no API key is required for read-only access. If you proxy through a corporate gateway, set RCSB_API_BASE to the internal endpoint.

Available Resources

The server exposes a consistent resource model. Each resource in the MCP response typically contains: id, type, mime_type, uri, size (optional), and metadata (key/value pairs).

Common resource types and examples:

Example simplified MCP resource (JSON)

{
  "id": "rcsb_pdb_1A8M_model",
  "type": "atomic_model",
  "mime_type": "chemical/x-mmcif",
  "uri": "https://files.rcsb.org/download/1A8M.cif",
  "metadata": {
    "pdb_id": "1A8M",
    "release_date": "2005-06-01",
    "experimental_method": "X-RAY DIFFRACTION",
    "resolution": "2.3"
  }
}

Use Cases

1. Retrieve model context for an LLM assistant

   • The assistant requests MCP context for a PDB ID, receives a bundle of resources (mmCIF, validation JSON, sequence) and uses metadata to prioritize content for answering structural questions.

   Example curl (resolve PDB entry, returns MCP resource list)

   curl "http://localhost:8080/mcp/resolve?pdb_id=1A8M" \
     -H "Accept: application/json"
   

2. Download and analyze the mmCIF programmatically

   • Use the provided resource URI to stream the mmCIF into a parser (BioPython/MDAnalysis) for automated feature extraction.

   Python example:

   import requests
   r = requests.get("http://localhost:8080/mcp/resolve?pdb_id=1A8M")
   resources = r.json().get("resources", [])
   mmcif = next(res for res in resources if res["type"] == "atomic_model")
   data = requests.get(mmcif["uri"]).text
   # parse data with your preferred library
   

3. Search-driven workflows

   • Combine a search frontend with the MCP server: query RCSB for matches (ligand, resolution, polymer type), then call the MCP resolve endpoint for each result to obtain context for downstream analysis or visualization.

Integration Tips

• Use caching when resolving many entries to avoid hammering the RCSB APIs.
• For large files (EM maps, structure factors), prefer streaming or signed temporary URLs; the server supports returning direct download links to RCSB file servers.
• Keep resource metadata minimal but consistent so downstream consumers can filter by experimental method, resolution, or release date.

Repository and source code: https://github.com/QuentinCody/rcsb-pdb-mcp-server

This server is intended for developers integrating structural data into model-driven applications and agents; it provides a predictable, machine-oriented view over the RCSB PDB ecosystem.