BindCraft

Model Context Protocol (MCP) server for protein binder design using BindCraft via Docker

Design high-affinity protein binders against target proteins using:

• AF2 Hallucination — Generate binder backbone conformations
• MPNN Sequence Design — Optimize amino acid sequences
• AF2 Validation — Predict and validate complex structures
• PyRosetta Scoring — Evaluate interface quality and energy

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/bindcraft_mcp:latest

# Register with Claude Code (runs as current user to avoid permission issues)
claude mcp add bindcraft -- docker run -i --rm --user `id -u`:`id -g` --gpus all --ipc=host -v `pwd`:`pwd` ghcr.io/macromnex/bindcraft_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 BindCraft 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/bindcraft_mcp.git
cd bindcraft_mcp

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

# Register with Claude Code (runs as current user to avoid permission issues)
claude mcp add bindcraft -- docker run -i --rm --user `id -u`:`id -g` --gpus all --ipc=host -v `pwd`:`pwd` bindcraft_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 'bindcraft' in the output

In Claude Code, you can now use all 5 BindCraft tools:

• bindcraft_design_binder — Synchronous binder design
• bindcraft_submit — Async design job submission
• bindcraft_check_status — Monitor job progress
• generate_config — Auto-generate configurations from PDB
• validate_config — Validate configuration files

---

Usage Examples

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

Example 1: Quick Binder Design

Design a binder against the target protein at /path/to/target.pdb. Use the bindcraft_design_binder tool with 3 designs, targeting chain A, with binder lengths between 65 and 150 residues.

Example 2: Generate Configuration from PDB

I have a target protein at /path/to/target.pdb. Can you generate a configuration file using generate_config with detailed analysis? Target hotspot residues should be automatically identified.

Example 3: Submit Async Design Job

Submit an async binder design job for the target at /path/to/target.pdb. Use bindcraft_submit with 10 designs, chain A, and output to /path/to/output/. Then monitor the job with bindcraft_check_status.

Example 4: Validate Configuration File

I have a configuration file at /path/to/config.json. Can you validate it using validate_config to ensure all parameters are correct before running the design?

Example 5: Batch Design with Auto Config

I have a target PDB at /path/to/target.pdb. First, generate an optimized config using generate_config, then submit an async design job with bindcraft_submit for 5 designs, and save results to /path/to/results/.

---

Next Steps

• Detailed documentation: See details.md for comprehensive guides on:

  • Local Python script usage (5 use cases)
  • All available MCP tools and parameters
  • Example workflows and tutorials
  • Configuration options
  • Troubleshooting

• Local Setup (Alternative to Docker): See details.md for conda-based environment setup if you prefer to run locally without Docker.

---

Key Features

✅ Synchronous Design — Fast results for single targets (1-10 minutes) ✅ Async Processing — Long-running jobs for complex designs (>10 minutes) ✅ Batch Processing — Process multiple targets concurrently ✅ Job Management — Complete lifecycle tracking and monitoring ✅ Auto Config — Generate optimized parameters from PDB files ✅ GPU Acceleration — Full CUDA and JAX/XLA support via Docker ✅ Error Handling — Robust error reporting and recovery

---

GPU Support

Both Docker approaches fully support:

• Multi-GPU systems (all GPUs automatically available in container)
• Single GPU setup
• CPU-only inference (via --gpus '""' if needed)

---

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

See details.md for more troubleshooting guidance.

---

License

Based on the original BindCraft repository by Martin Pacesa and colleagues.