# 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:
```bash
uv sync
```

Or with pip:
```bash
pip install -e .
```

## Running the Server

### As a Standalone Server

```bash
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`

```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