cnyambura/rcsb-mcp

RCSB PDB MCP Server

An MCP (Model Context Protocol) server that provides tools for interacting with the RCSB Protein Data Bank API.

Overview

This server exposes tools for:

• Querying PDB entry information
• Retrieving polymer entity details
• Downloading structure files in various formats
• Making custom API queries to RCSB Data API

Installation

1. Install dependencies using uv:

uv sync

Or with pip:

pip install -e .

Running the Server

As a Standalone Server

python server.py

With Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "rcsb-pdb": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/cnyambura/Documents/rcsb_api/api/rcsb-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

After adding the configuration, restart Claude Desktop.

Available Tools

1. get_pdb_entry

Get comprehensive information about a PDB entry.

Parameters:

• pdb_id (string): 4-character PDB identifier (e.g., '1ABC', '7BQY')

Returns: JSON with structure information including title, experimental method, resolution, dates, authors, and source organism.

Example:

get_pdb_entry("1ABC")

2. get_polymer_entity

Get information about a polymer entity (protein, DNA, RNA) within a PDB entry.

Parameters:

• pdb_id (string): 4-character PDB identifier
• entity_id (string, optional): Entity number (default: "1")

Returns: JSON with molecule name, sequence, molecular weight, entity type, and source organism.

Example:

get_polymer_entity("1ABC", "1")

3. download_structure_file

Download a structure file from RCSB PDB.

Parameters:

• pdb_id (string): 4-character PDB identifier
• file_format (string, optional): Format to download (default: "pdb")
  • pdb: PDB format
  • cif: mmCIF format
  • xml: PDBML/XML format
  • pdb.gz: Compressed PDB
  • cif.gz: Compressed mmCIF
  • xml.gz: Compressed XML
• output_dir (string, optional): Directory to save the file
• filename (string, optional): Custom filename

Returns: JSON with download status and file path.

Example:

download_structure_file("1ABC", "pdb", "/path/to/output")

4. query_rcsb_api

Make a custom query to the RCSB Data API.

Parameters:

• endpoint (string): API endpoint path (e.g., 'assembly/1ABC-1', 'uniprot/P12345')
• params (string, optional): JSON string of query parameters

Common endpoints:

• entry/{pdb_id}: Entry-level information
• polymer_entity/{pdb_id}_{entity_id}: Polymer entity info
• assembly/{pdb_id}-{assembly_id}: Biological assembly info
• nonpolymer_entity/{pdb_id}_{entity_id}: Small molecule/ligand info
• uniprot/{uniprot_id}: UniProt cross-reference

Returns: JSON containing the API response.

Example:

query_rcsb_api("assembly/1ABC-1")

5. search_pdb_by_organism

Get information about how to search for PDB entries by organism.

Parameters:

• organism (string): Organism name (e.g., 'Homo sapiens', 'E. coli')

Returns: Instructions and example queries for searching by organism.

Example Usage with Claude

Once connected to Claude Desktop, you can ask:

• "Get information about PDB entry 1ABC"
• "Download the structure file for 7BQY in mmCIF format"
• "Show me the polymer entity details for PDB 4HHB entity 1"
• "Query the assembly information for 1ABC assembly 1"

Project Structure

rcsb-mcp/
├── rcsb_api.py        # Core RCSB API functions
├── server.py          # FastMCP server implementation
├── pyproject.toml     # Project dependencies
└── README.md          # This file

API Documentation

For more information about the RCSB Data API, visit:

• https://data.rcsb.org/
• https://www.rcsb.org/docs/programmatic-access/web-services-overview

License

MIT