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.

# 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.

# 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:

# 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 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/:

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?

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?

# 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:

# 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 for:

• Manual conda environment setup

• Direct Python script execution

• Custom configuration options

License

Based on the original BoltzGen repository by Hannes Stark et al. MCP integration built using FastMCP framework.