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.,Nature2024, 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 进程用）pipinstall--user'mcp>=2.0'# 2. AF3 conda env 装 v3.0.1 + hmmerconda create-nAF3python=3.11-yconda activate AF3 pipinstallalphafold3==3.0.1 condainstall-cbioconda hmmer-y# 3. clone AF3 v3.0.1 源码（pip 包不含可执行 run_alphafold.py，# 不 clone 会报 ModuleNotFoundError: No module named 'shards'）gitclone https://github.com/google-deepmind/alphafold3.git ~/app/alphafold3-v301-bv3.0.1# 4. 权重 + 数据库（向 AF3 服务器申请；学术许可）ls~/AF/datasets/# 含 af3.bin 1.1 GBls~/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.whichPath("/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）。

关键点：

1. 用户全程不说"AF3"、不说"MSA"、不说"conda"——Agent 通过 MCP 工具自己处理。
2. 长任务不阻塞 Agent——submit 后 status polling 是异步的。本机单 HDD 实测 GFP 全程约 3h42，瓶颈在 MSA 磁盘 IO 不是 GPU。
3. 结果是人话不是数字——“结构很靠谱"而不是"pTM=0.91, pLDDT=92.56”。

§7. pTM / pLDDT / ipTM 解读

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

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

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

按时间顺序：

1. mcp 2.x 改名：FastMCP→MCPServer，1.x 教程代码直接 ModuleNotFoundError。修法：pip install --user 'mcp>=2.0'后用from mcp.server.mcpserver import MCPServer。
2. 缺from pathlib import Path：server 顶层没 importPath，新写的_env_or_default用Path()报NameError。修法：补 import。
3. read_af3_confidence字段名错：原版找plddt/iptm顶层字段，实际 AF3 v3.0.1 输出是ptm顶层 +chain_pair_iptm[0][1]嵌套 +atom_plddts在confidences.json。修法：读ptm，mean pLDDT 从atom_plddts算。
4. PYTHONPATH 污染 conda env：mcp_servers 给 server 进程传了系统 py3.10 的 site-packages，但 conda AF3 是 py3.11——subprocess 启动时import zstandard撞 py3.10 的 .so 报 ModuleNotFoundError。修法：env.pop("PYTHONPATH", None)。
5. os.environ.get('HOME')返回 None：Hermes 沙箱启动 server 时不传 HOME，AF3 内部pathlib.Path(None)报 TypeError。修法：env.setdefault("HOME", str(Path.home()))显式补。
6. 系统 python 没 jax：用/usr/bin/python3（系统 py3.10）跑 wrapper，import jax报 ModuleNotFoundError。修法：subprocess 用 conda env 自己的 python（_find_af3_conda_env_python()自动探测）。

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

• jax+alphafold3.cpp 段错误：AF3 v3.0.x 先 import alphafold3.cpp 再 import jax 会在jaxlib.xla_client.initialize_pjrt_pluginSegFault，无 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/python3args:-~/.hermes/af3-mcp/af3_mcp_server.pyenv:PYTHONPATH:~/.local/lib/python3.10/site-packagesAF3_INPUT:~/af_inputAF3_OUTPUT:~/af_outputAF3_MODELS:~/AF/datasetsAF3_DBS:~/AF/datasets/public_databases_AF3_AF3ComplexAF3_CONDA_ENV:~/anaconda3/envs/AF3AF3_RUN_ALPHAFOLD:~/app/alphafold3-v301/run_alphafold.pytimeout:180connect_timeout:60enabled: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

参考来源

1. google-deepmind/alphafold3 README——docker 命令与权重许可出处。
2. AF3 input 文档——dialect/version 与配体写法。
3. MCP Python SDK——2.x API（MCPServer）出处。
4. Abramson J, et al.Nature2024. DOI: 10.1038/s41586-024-07487-w。
5. 本机实测：4 工具协议级 handshake + conda 真跑 GFP（pTM 0.91, pLDDT 92.6）+ 6 处 bug 修复 diff。
6. mcp-development skill（~/.hermes/skills/autonomous-ai-agents/mcp-development/）——自建 MCP 的模板。

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

我的专栏