# BoltzGen MCP

**AI-powered protein design via Docker and Model Context Protocol**

Design protein binders, peptide binders, and custom proteins using BoltzGen with:
- **Protein Binder Design** — Design proteins that bind to target proteins
- **Peptide Binder Design** — Generate peptides with optimized sequences
- **Multiple Protocols** — Support for antibodies, nanobodies, and small molecule interactions
- **Async Job Queue** — FIFO scheduling with GPU-aware resource management
- **Docker Deployment** — Pre-built images with all dependencies included

## Quick Start with Docker

### Approach 1: Pull Pre-built Image from GitHub

The fastest way to get started. A pre-built Docker image is automatically published to GitHub Container Registry on every release.

```bash
# Pull the latest image
docker pull ghcr.io/macromnex/boltzgen_mcp:latest

# Register with Claude Code (runs as current user to avoid permission issues)
claude mcp add boltzgen -- docker run -i --rm --user `id -u`:`id -g` --gpus all --ipc=host -v `pwd`:`pwd` ghcr.io/macromnex/boltzgen_mcp:latest
```

**Note:** Run from your project directory. `${pwd}` expands to the current working directory.

**Requirements:**
- Docker with GPU support (`nvidia-docker` or Docker with NVIDIA runtime)
- Claude Code installed

That's it! The BoltzGen MCP server is now available in Claude Code.

---

### Approach 2: Build Docker Image Locally

Build the image yourself and install it into Claude Code. Useful for customization or offline environments.

```bash
# Clone the repository
git clone https://github.com/MacromNex/boltzgen_mcp.git
cd boltzgen_mcp

# Build the Docker image
docker build -t boltzgen_mcp:latest .

# Register with Claude Code (runs as current user to avoid permission issues)
claude mcp add boltzgen -- docker run -i --rm --user `id -u`:`id -g` --gpus all --ipc=host -v `pwd`:`pwd` boltzgen_mcp:latest
```

**Note:** Run from your project directory. `${pwd}` expands to the current working directory.

**Requirements:**
- Docker with GPU support
- Claude Code installed
- Git (to clone the repository)

**About the Docker Flags:**
- `-i` — Interactive mode for Claude Code
- `--rm` — Automatically remove container after exit
- `--user ${id -u}:${id -g}` — Runs the container as your current user, so output files are owned by you (not root)
- `--gpus all` — Grants access to all available GPUs
- `--ipc=host` — Uses host IPC namespace for better performance
- `-v` — Mounts your project directory so the container can access your data

---

## Verify Installation

After adding the MCP server, you can verify it's working:

```bash
# List registered MCP servers
claude mcp list

# You should see 'boltzgen' in the output
```

In Claude Code, you can now use all 8 BoltzGen tools:
- `boltzgen_run` — Synchronous protein design
- `boltzgen_submit` — Submit async design jobs
- `boltzgen_check_status` — Monitor job progress by output directory
- `boltzgen_job_status` — Check job by ID
- `boltzgen_queue_status` — View queue and GPU availability
- `boltzgen_cancel_job` — Cancel jobs
- `boltzgen_configure_queue` — Set max workers and GPU configuration
- `boltzgen_resource_status` — Verify GPU resource management

---

## Next Steps

- **Detailed documentation**: See [details.md](details.md) for comprehensive guides on:
  - Local Python environment setup (alternative to Docker)
  - Available MCP tools and parameters
  - Example workflows and tutorials
  - Configuration file formats
  - Troubleshooting

---

## Usage Examples

Once registered, you can use the BoltzGen tools directly in Claude Code. Here are some common workflows:

### Example 1: Quick Protein Design

```
Submit protein binder design for @examples/data/1g13prot.yaml
with output_dir "results/1g13_design" and num_designs 5
```

### Example 2: Peptide Binder with Quality Focus

```
Submit peptide binder design for @examples/data/beetletert.yaml
with output_dir "results/peptide_design", alpha 0.01 (quality focused),
and num_designs 10
```

### Example 3: Async Job Submission and Monitoring

```
1. Submit async protein design for @examples/data/1g13prot.yaml
   with output_dir "results/async_design" and num_designs 10
2. Check job status every 30 seconds
3. When complete, show me the generated structures
```

### Example 4: Batch Processing Multiple Targets

```
Submit batch protein design for these configs:
- @examples/data/1g13prot.yaml (1G13 protein)
- @examples/data/beetletert.yaml (BeetleTert)
- @examples/data/pdl1_simplified.yaml (PDL1)

Save to output_base_dir "results/batch" with num_designs 5 each
```

### Example 5: Validate Configuration Before Design

```
Validate these configs and show me any issues:
- @examples/data/1g13prot.yaml
- @examples/data/beetletert.yaml
- @examples/data/chorismite.yaml
```

### Example 6: Monitor Job Queue

```
Show me the current job queue status and available GPUs
```

---

## Demo Data

Example configuration files are included in `examples/data/`:

| File | Description | Use Case |
|------|-------------|----------|
| `1g13prot.yaml` | 1G13 protein binder design | Protein-protein interactions |
| `beetletert.yaml` | BeetleTert peptide design | Peptide drug discovery |
| `pdl1_simplified.yaml` | PDL1 antibody design | Antibody engineering |
| `chorismite.yaml` | Small molecule binding | Enzyme design |
| `penguinpox.yaml` | Nanobody design | Nanobody development |

---

## Supported Protocols

All tools support the following design protocols:
- `protein-anything` (default) — General protein binder design
- `peptide-anything` — Peptide design with cysteine filtering
- `protein-small_molecule` — Small molecule interactions
- `nanobody-anything` — Nanobody CDR design
- `antibody-anything` — Antibody design

## GPU Support

Docker setup fully supports:
- Multi-GPU systems (specify device via `cuda:0`, `cuda:1`, etc.)
- Single GPU setup
- CPU-only inference (slower, use `cpu` device)

---

## Troubleshooting

**Docker not found?**
```bash
docker --version  # Install Docker if missing
```

**GPU not accessible?**
- Ensure NVIDIA Docker runtime is installed
- Check with `docker run --gpus all ubuntu nvidia-smi`

**Claude Code not found?**
```bash
# Install Claude Code
npm install -g @anthropic-ai/claude-code
```

**Permission issues with output files?**
The Docker setup automatically runs as your current user. If you still see permission issues:
```bash
# Rebuild with your user ID
docker build --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g) -t boltzgen_mcp:latest .
```

---

## Local Setup (Alternative to Docker)

For development or custom environments, see [details.md](details.md#installation) for:
- Manual conda environment setup
- Direct Python script execution
- Custom configuration options

---

## License

Based on the original [BoltzGen](https://github.com/HannesStark/boltzgen) repository by Hannes Stark et al.
MCP integration built using [FastMCP](https://github.com/jlowin/fastmcp) framework.