Boltz MCP 服务器

通过 Docker 使用 Boltz2 进行结构和亲和力预测

一款适用于 Boltz2 蛋白质建模的 MCP（模型上下文协议）服务器，具备 13 项工具功能：

• 从序列或 YAML 配置预测蛋白质 3D 结构
• 预测蛋白质-配体结合亲和力
• 提交长时间运行的作业并进行异步监控
• 跟踪和检索作业结果
• 验证蛋白质序列和配体 SMILES
• 批量处理多个序列
• 支持预计算 MSA，实现快速配体筛选

Docker 快速入门

方法 1：从 GitHub 拉取预构建镜像

# Pull the latest image
docker pull ghcr.io/macromnex/boltz_mcp:latest

# Register with Claude Code
claude mcp add boltz -- docker run -i --rm \
  --user `id -u`:`id -g` --gpus all --ipc=host \
  -v ~/.boltz:/opt/boltz_cache:ro \
  -v `pwd`:`pwd` \
  ghcr.io/macromnex/boltz_mcp:latest

方法 2：本地构建 Docker 镜像

git clone https://github.com/MacromNex/boltz_mcp.git
cd boltz_mcp
docker build -t boltz_mcp:latest .

claude mcp add boltz -- docker run -i --rm \
  --user `id -u`:`id -g` --gpus all --ipc=host \
  -v ~/.boltz:/opt/boltz_cache:ro \
  -v `pwd`:`pwd` \
  boltz_mcp:latest

要求：

• 支持 GPU 的 Docker（nvidia-docker 或带有 NVIDIA 运行时的 Docker）
• Boltz2 模型检查点位于 ~/.boltz（首次本地运行时自动下载）
• 已安装 Claude Code

Docker 标志说明

标志	用途
-i	MCP 标准输入输出的交互模式
--rm	退出后移除容器
--user `id -u`:`id -g`	以当前用户身份运行（输出文件归您所有）
--gpus all	访问所有 GPU
--ipc=host	用于 PyTorch 性能的主机 IPC 命名空间
-v ~/.boltz:/opt/boltz_cache:ro	挂载缓存的模型检查点（只读）
-v path:path	挂载工作目录以进行输入/输出访问

用于快速筛选的预计算 MSA

当针对同一蛋白质筛选多个配体时，挂载预计算的 MSA 目录可跳过缓慢的 MSA 服务器查询（每次运行节省约 5 分钟）：

claude mcp add boltz -- docker run -i --rm \
  --user `id -u`:`id -g` --gpus all --ipc=host \
  -v ~/.boltz:/opt/boltz_cache:ro \
  -v /path/to/msa_files:/opt/msa:ro \
  -v `pwd`:`pwd` \
  boltz_mcp:latest

然后将 msa_path="/opt/msa/protein.a3m" 传递给任何预测工具。MSA .a3m 文件会在首次使用 --use_msa_server 运行时自动生成，可在输出目录的 msa/ 文件夹下找到。

---

验证安装

claude mcp list
# You should see 'boltz' in the output

可用工具（共 13 个）：

• simple_structure_prediction / simple_affinity_prediction — 同步预测
• submit_structure_prediction / submit_affinity_prediction / submit_batch_structure_prediction — 异步任务
• get_job_status / get_job_result / get_job_log / cancel_job / list_jobs — 任务管理
• validate_protein_sequence / validate_ligand_smiles — 输入验证
• list_example_data — 列出捆绑示例

---

使用示例

快速结构预测

Predict the structure of this protein: MVLSEGEWQLVLHVWAKVEADVAGHGQDILIRLFKSHPETLEKFDRFKHLKTEREQESRKEAAG. Save to /path/to/results/.

蛋白质-配体亲和力

Predict binding affinity between protein MVLSE... and aspirin (SMILES: CC(=O)Oc1ccccc1C(=O)O). Use simple_affinity_prediction.

使用预计算MSA进行快速配体筛选

Screen these 10 ligands against KRAS using simple_affinity_prediction with msa_path="/opt/msa/kras.a3m" for each.

具有潜力的高质量结构

Submit a structure prediction with use_potentials=True for the sequence in /path/to/protein.fasta. Monitor until complete.

---

命令行界面使用方法（无 MCP）

# Structure prediction
./env/bin/python scripts/structure_prediction.py --sequence "MVLSE..." --output results/out

# Affinity prediction
./env/bin/python scripts/affinity_prediction.py \
  --protein-seq "MVLSE..." --ligand-smiles "CC(=O)O" --output results/out

# With pre-computed MSA (skips MSA server, much faster)
./env/bin/python scripts/affinity_prediction.py \
  --protein-seq "MVLSE..." --ligand-smiles "CC(=O)O" \
  --msa-path /path/to/protein.a3m --output results/out

---

故障排除

未找到 Docker？

docker --version  # Install Docker if missing

GPU 无法访问？

• 确保已安装 NVIDIA Docker 运行时
• 使用 docker run --gpus all ubuntu nvidia-smi 命令进行检查

模型检查点缺失？

• 先运行一次本地预测，模型会自动下载到 ~/.boltz
• 或在运行前设置 BOLTZ_CACHE=/path/to/cache

Claude Code 未找到？

npm install -g @anthropic-ai/claude-code

---

后续步骤

有关可用工具、YAML 配置格式、本地设置和性能优化的全面指南，请参见 detail.md。

许可证

MIT