AI Agent 时代的生物计算：AlphaFold 3 MCP Server 搭建与本地部署

本文收录于专栏 AI Agent智能体系列 —— 专栏系统覆盖 AI Agent 记忆、工具、插件与实战，点击订阅可跟踪后续更新。

自建 af3-mcp，通过Agent调用AlphaFold3。这篇把过程摊开：怎么从一个能启动的 server 走到 4 步链路全打通、能读AlphaFold3结果，以及如何给Agent"安装 MCP"。 本机 conda 环境实测：4 个工具的 JSON-RPC handshake + 真跑 submit_af3_job（conda 后台 spawn AF3 v3.0.1 wrapper）+ read_af3_confidence 读 GFP 真实结果——pTM = 0.91、pLDDT = 92.6。

关键字：AlphaFold 3、MCP server、Model Context Protocol、conda spawn、pTM、pLDDT、JSON-RPC、路径自动探测

AF3 包成 MCP server
├─ 为什么自建：MacromNex 撞墙（a3m 缺脚本 / docker 段错误 / 路径写死）
├─ 4 步链路：build JSON → conda spawn → 轮询状态 → 读置信度
├─ 零硬编码：4 级路径探测（env > 脚本旁 > $HOME > PATH）
├─ 实测：GFP pTM 0.91 / pLDDT 92.6，6 处 bug 修完
└─ 接入：Hermes config.yaml / Claude Code .mcp.json

目录

• §1. 场景痛点：装 MCP 容易，让 MCP 真跑不容易
• §2. 4 工具链路设计：组 → 跑 → 查 → 读
• §3. 环境准备（实测版本）
• §4. 4 级路径自动探测：零硬编码
• §5. 协议级实测：4 步链路全打通
• §6. 对话演示：用户说人话 → 自动出结构
• §7. pTM / pLDDT / ipTM 解读
• §8. 踩坑清单：6 处实测 bug
• §9. 接到 Agent：两边各几行
• §10. 总结与资产包

相关教程与核心文献

核心文献：Abramson et al., Nature 2024, DOI: 10.1038/s41586-024-07487-w（AF3 原始论文，pTM/pLDDT/ipTM 定义出处）。

§1. 场景痛点：装 MCP 容易，让 MCP 真跑不容易

实验室的真实场景：AF3 装在共享 GPU 服务器上，五个人都要用——每人 SSH 上去配一遍路径、抄一遍命令，路径改了全组重教一遍；任务一跑几小时，谁都记不住自己的任务跑到哪了。这正是 MCP 的主场：server 常驻服务器，持有环境和任务状态；所有人的 Agent 通过 stdio 直连，schema 强校验参数，管理员改一处全组生效。

问题是有 2 个候选 AF3 MCP（cyanheads/protein 是结构查询不是结构生成，不在本文对比范围），实测只有 1 个能跑：

结论：MacromNex 开源但质量可疑，实测后已从 config.yaml 删除（连同 boltz_mn / protein_sol 共 3 个 MacromNex MCP）。最终方案是自建 af3-mcp：4 个工具，跑本机 conda AF3 环境，不依赖 docker。

§2. 4 工具链路设计：组 → 跑 → 查 → 读

你的笔记本 本机 conda AF3
Agent（Hermes/DSH/Claude Code）⇄ af3-mcp ⇄ conda spawn → AF3 v3.0.1
mcp__af3__build_af3_json 组装输入 JSON
mcp__af3__submit_af3_job 提交任务（conda 后台 spawn，setsid）
mcp__af3__get_af3_job_status 查状态
mcp__af3__read_af3_confidence 解读结果（人话）

4 个工具不是凭空设计的，对应 AF3 流程的最小完备集：

关键设计：状态靠文件存在性，不靠 docker ps / in-memory dict——“done” = <name>_summary_confidences.json 存在。server 不维护任务表，conda spawn 被 kill 后状态依然准确。任何一步出错都返回 isError: true + 可读错误，Agent 能自己处理；schema 强制字段类型（protein_sequence 非空、name 禁非法字符），违规在协议层就拒。

协议时序图：下面这条 JSON-RPC 握手序列

上图：客户端启动 → initialize 握手（protocol 2025-06-18）→ tools/list 发现 → 4 次 tools/call。绿色路径是成功（conda 真跑），红色是错误路径（结果未就绪时 isError 不崩溃）。

§3. 环境准备（实测版本）

# 1. 系统 Python 3.10 装 mcp 2.x（server 进程用）
pip install –user 'mcp>=2.0'

# 2. AF3 conda env 装 v3.0.1 + hmmer
conda create -n AF3 python=3.11 -y
conda activate AF3
pip install alphafold3==3.0.1
conda install -c bioconda hmmer -y

# 3. clone AF3 v3.0.1 源码（pip 包不含可执行 run_alphafold.py，
# 不 clone 会报 ModuleNotFoundError: No module named 'shards'）
git clone https://github.com/google-deepmind/alphafold3.git ~/app/alphafold3-v301 -b v3.0.1

# 4. 权重 + 数据库（向 AF3 服务器申请；学术许可）
ls ~/AF/datasets/ # 含 af3.bin 1.1 GB
ls ~/AF/datasets/public_databases_AF3_AF3Complex/ # 含 9 个 .fa 文件，共 357 GB

# 5. GPU 驱动 + CUDA 12.x（消费级 GPU 需 –flash_attention_implementation=xla）
nvidia-smi

§4. 4 级路径自动探测：零硬编码

这是与其它 AF3 MCP 候选最大的区别——AF3 conda env 路径、源码路径、权重路径不进代码，server 内部 4 级 fallback 自动探测；同一份代码零改动换机器（布局不同时只改 Agent 端 env 即可）。

# 0. env var 显式覆盖 (mcp_servers.env 传, 优先级最高)
os.environ.get("AF3_RUN_ALPHAFOLD")
# 1. Path(__file__).parent 自定位 (server 旁边 helper scripts)
Path(__file__).parent / "scripts" / "run_af3_jaxfirst.py"
# 2. Path.home() 用户级默认 (Linux $HOME 是约定路径, 跨用户通用)
Path.home() / "anaconda3" / "envs" / "AF3"
# 3. FHS 系统级 + shutil.which
Path("/opt/conda/envs/AF3"), shutil.which("run_alphafold.py")

模块级常量声明（server 启动一次，5 个常量自动配置）：

AF3_INPUT = _env_or_default("AF3_INPUT", Path.home() / "af_input", Path("/var/lib/af3/input"))
AF3_OUTPUT = _env_or_default("AF3_OUTPUT", Path.home() / "af_output", Path("/var/lib/af3/output"))
AF3_MODELS = _env_or_default("AF3_MODELS", Path.home() / "AF" / "datasets",
Path("/opt/af3/weights"), Path("/data/af3/weights"))
AF3_DBS = _env_or_default("AF3_DBS", Path.home() / "AF" / "datasets" / "public_databases_AF3_AF3Complex",
Path("/opt/af3/databases"), Path("/data/af3/databases"))
AF3_CONDA_ENV = _env_or_default("AF3_CONDA_ENV", Path.home() / "anaconda3" / "envs" / "AF3",
Path("/opt/conda/envs/AF3"), Path("/usr/local/anaconda3/envs/AF3"))

§5. 协议级实测：4 步链路全打通

不靠 agent，用一个 25 行的 Python 脚本（资产包 test_client.py）走完整 JSON-RPC handshake + 调全部 4 个工具。真实输出，2026-10-04 本机 conda 真跑：

=== 1. initialize ===
server: {'name': 'af3'} | protocol: 2025-06-18

=== 2. tools/list ===
– build_af3_json: 组装 AF3 输入 JSON…（schema 完整）
– submit_af3_job: conda spawn 后台（setsid + log 路径）
– get_af3_job_status: done / pending
– read_af3_confidence: 读 summary_confidences.json + atom_plddts 算 mean → 大白话

=== 3. build_af3_json（GFP, P42212, 238 aa）===
[OK] ~/af_input/gfp_demo.json: 蛋白链 A (238 aa) + 无配体, seeds=[1]

=== 4. submit_af3_job（conda 真跑分支）===
[SUBMITTED] AF3 conda 后台进程已启动
PID: 100181
log: ~/af_output/gfp_demo.submit.log
cmd: …/envs/AF3/bin/python …/scripts/run_af3_jaxfirst.py –json_path=… –model_dir=… –db_dir=…

=== 5. get_af3_job_status ===
pending # MSA 阶段，4 个 jackhmmer 并发打 357 GB 数据库

=== 6. read_af3_confidence("gfp_demo"，跑完后）===
pTM=0.91（很靠谱）；ipTM=0.00（无配体，纯蛋白无 ipTM）；pLDDT=92.6（结构很靠谱）

关键 4 步全部跑通：submit 走 conda env python 后台 spawn（真实 AF3 进程，能 pgrep -af run_af3_jaxfirst.py 看到）；status 检测到 summary_confidences.json 存在即 done；read 解析真 GFP 结果。从 dry-run 到真跑之间修了 6 处 bug，清单见 §8。

§6. 对话演示：用户说人话 → 自动出结构

挂上 MCP 后，用户不需要知道任何 AF3 / conda / MSA / hmmer 概念：

用户说：“帮我预测 GFP 的结构，UniProt P42212”

Hermes Agent 自动四步：

# 步骤 1：组装 JSON（Agent 内部拉 UniProt FASTA 取序列）
mcp__af3__build_af3_json(
name="gfp_demo",
protein_sequence="MSKGEELFTGVVPILVELDGDVNGHKFSVSGEGEGDATYGKLTLKFICTTGKLPVPWPTLVTTFSYGVQCFSRYPDHMKQHDFFKSAMPEGYVQERTIFFKDDGNYKTRAEVKFEGDTLVNRIELKGIDFKEDGNILGHKLEYNYNSHNVNYVIMADKQKNGIKVNFKIRHNIEDGSVQLADHYQQNTPIGDGPVLLPDNHYLSTQSALSKDPNEKRDHMVLLEFVTAAGITHGMDELYK"
)
# → "[OK] ~/af_input/gfp_demo.json: 蛋白链 A (238 aa) + 无配体, seeds=[1]"

# 步骤 2：提交任务（conda spawn，setsid 独立进程组）
mcp__af3__submit_af3_job(name="gfp_demo")
# → "[SUBMITTED] AF3 conda 后台进程已启动 PID: 100181 log: ~/af_output/gfp_demo.submit.log"

# 步骤 3：轮询状态（Agent 自动每 30s 调一次直到 done）
mcp__af3__get_af3_job_status(name="gfp_demo")
# → "pending" → "pending" → … → "done"

# 步骤 4：解读结果（人话）
mcp__af3__read_af3_confidence(name="gfp_demo")
# → "pTM=0.91（很靠谱）；ipTM=0.00（无配体）；pLDDT=92.6（结构很靠谱）"

Agent 最终回复：

GFP 预测完成。

• 整体质量：pTM = 0.91，pLDDT mean = 92.6，结构很靠谱。
• 产物：~/af_output/gfp_demo/gfp_demo_model.cif（预测 mmCIF）+ gfp_demo_confidences.json（每残基 pLDDT）。

关键点：

§7. pTM / pLDDT / ipTM 解读

上图：pLDDT（每个残基的自信程度）和 ipTM（蛋白-配体结合姿势可信度）的阈值含义。

注解：GFP 结果里 ipTM=0.00 不是 bug——纯蛋白场景 AF3 不算 pair-wise pTM，显示"无配体，无 ipTM"比硬给 0.00 更清楚。

§8. 踩坑清单：6 处实测 bug

按时间顺序：

已知的非 bug（设计使然，勿再排查）：

• jax+alphafold3.cpp 段错误：AF3 v3.0.x 先 import alphafold3.cpp 再 import jax 会在 jaxlib.xla_client.initialize_pjrt_plugin SegFault，无 traceback。conda 直跑必须 wrapper 先 import jax; jax.devices() 强初始化（scripts/run_af3_jaxfirst.py 就是这个 wrapper）。
• conda 直跑找不到 jackhmmer：subprocess 不继承 shell PATH。修法：env["PATH"] = f"{conda_bin}:{env.get('PATH', '')}" 注入。
• Mock MSA 跑不通：unpairedMsa: "" 跳过 pipeline 会报 ValueError: Protein chain 1 is missing unpaired MSA.。必须跑真 MSA，这是 AF3 的设计选择。
• 单机单盘跑 MSA 慢：4 个 jackhmmer 并发打同一块 HDD，CPU 4% / IO 100%；BFD 库 42 分钟，uniref90 库 2h47min。多分子建议串行，不要并行抢盘。

§9. 接到 Agent：两边各几行

Hermes Desktop（~/.hermes/config.yaml 加 mcp_servers.af3 块，改完需重启 gateway 生效）：

mcp_servers:
af3:
command: /usr/bin/python3
args:
– ~/.hermes/af3–mcp/af3_mcp_server.py
env:
PYTHONPATH: ~/.local/lib/python3.10/site–packages
AF3_INPUT: ~/af_input
AF3_OUTPUT: ~/af_output
AF3_MODELS: ~/AF/datasets
AF3_DBS: ~/AF/datasets/public_databases_AF3_AF3Complex
AF3_CONDA_ENV: ~/anaconda3/envs/AF3
AF3_RUN_ALPHAFOLD: ~/app/alphafold3–v301/run_alphafold.py
timeout: 180
connect_timeout: 60
enabled: true

Claude Code / DSH（项目级 .mcp.json）：

{"mcpServers": {"af3": {
"command": "python3",
"args": ["~/.hermes/af3-mcp/af3_mcp_server.py"],
"env": {"AF3_CONDA_ENV": "~/anaconda3/envs/AF3"}}}}

挂上后模型看到 mcp__af3__build_af3_json 等四个原生工具（mcp__<server>__<tool> 命名两家同形），直接说"预测 GFP 的结构"即可。env 块里的路径也可全部省略——§4 的 4 级探测会自动找，同一份 server 代码换机只改 env。

§10. 总结与资产包

2 个 AF3 MCP 候选 → 1 个能跑通。能跑通的关键不是"装 MCP"的能力（npm install 谁都会），而是修 MCP 的能力——读源码、追段错误、4 级路径自动探测、conda spawn 真跑。

完整MCP代码：

• 附件包：amber-mcp-local

参考来源

系列导航： 专栏全集 AI Agent智能体系列

我的专栏