vmd-hydrate-mcp

vmd-hydrate-mcp

通过任何大模型驱动 VMD —— 渲染 GROMACS/LAMMPS 轨迹，并通过模型上下文协议分析笼形水合物笼。

快速开始 · 功能 · MCP 工具 · 用法 · 한국어

---

说明

一个 MCP 服务，可让 Claude（或任何 MCP 客户端）直接控制 VMD —— 加载 GROMACS/LAMMPS 轨迹、识别笼形水合物笼（sI/sII/sH）、编写无头渲染脚本，并计算序参量（F3/F4）和氢键网络，将分子动力学分析变成对话体验。与现有的 VMD MCP 不同，它会保留有状态的 VMD 会话，默认安全，并实现了其他 MCP 都没有的一项功能：水合物笼科学分析。

查看实际效果

每一帧都是通过 MCP 服务完全驱动的真实无头 VMD（Tachyon）渲染。sII 笼 —— 128 × 5¹² + 60 × 5¹²6⁴ —— 是由本仓库识别的，并非模拟生成。 · ▶ 高清 MP4 全片

功能

• 笼形水合物笼识别 -- 从氢键网络中查找并分类水合物笼（5¹²、5¹²6²、5¹²6⁴……），并标注晶体结构（sI/sII/sH）。已在 sII 基准测试中验证（128 个小笼，结果精确）。
• 照片级真实感、由提示词控制的笼体渲染 -- 笼体采用环境光遮蔽和阴影渲染，默认使用正交投影，每种笼型使用一种统一颜色（精选配色：5¹²=青色、5¹²6⁴=红色……）。只需提出请求：“仅显示 sII 大笼，用洋红色并加粗线条”，MCP 就会筛选、重新着色并加粗线条。
• 有状态的 VMD 会话 -- 持久运行的 VMD 进程（Tcl 套接字服务）会在多次工具调用间保留分子、选择集和相机状态，无需每条命令都重新加载。
• 水合物序参量 -- 使用纯 NumPy 计算 F3（四面体性）和 F4（⟨cos 3φ⟩），与参考值验证到小数点后 6 位（sII 基准测试中的 F4 = 0.926698）。
• 氢键网络 -- 水分子间氢键图及配位统计，是识别笼体的基础。
• 无头渲染 -- 使用 CPU 进行 Tachyon 光线追踪，生成 PNG，无需显示器或 GPU，并以内嵌图像形式返回。适用于笔记本电脑、服务器和 HPC。
• 有人值守（GUI）模式 -- 默认完全在后台运行，也可设置 VMD_HYDRATE_MCP_DISPLAY=gui 打开可见的 VMD 窗口，实时观察 Claude 加载、着色、旋转并渲染系统。
• GROMACS + LAMMPS -- 一个服务即可读取 .gro/.xtc/.trr、LAMMPS .data/dump、PDB、DCD 和 mmCIF。
• 默认安全 -- 文件系统允许列表 + Tcl 命令允许列表（而非可绕过的拒绝列表）+ 仅限环回连接且需令牌验证的控制套接字。不暴露 run_tcl 这一危险操作。
• 原生支持 MCP -- 清晰的英文工具名称和类型化输出；适用于 Claude Desktop、Claude Code 和任何 MCP 客户端。

快速开始

重要

需要本地安装 VMD（2.0b1 或 1.9.4+）—— 此服务驱动的是你自己的 VMD；注册表或软件包均不包含 VMD。在 macOS 上，VMD 位于 .app 内，因此如果 vmd 不在 PATH 中，请设置 VMD_BIN。（纯水合物分析和测量工具仍可在没有 VMD 的情况下使用。）

安装

通过 uvx 零安装（推荐）：

uvx vmd-hydrate-mcp                                  # run the server
uvx --from 'vmd-hydrate-mcp[mda]' vmd-hydrate-mcp    # + MDAnalysis for measures/selection

或从源码安装：

git clone https://github.com/wjgoarxiv/vmd-hydrate-mcp.git
cd vmd-hydrate-mcp && uv pip install -e ".[mda]"

注册到 MCP 客户端

Claude Code — 一条命令：

claude mcp add vmd-hydrate -- uvx vmd-hydrate-mcp

Claude Desktop / 任意客户端 — 添加到 mcpServers 配置中（或提交项目 .mcp.json）：

{
  "mcpServers": {
    "vmd-hydrate": {
      "command": "uvx",
      "args": ["vmd-hydrate-mcp"],
      "env": { "VMD_HYDRATE_MCP_ALLOW_DIR": "/path/to/your/data" }
    }
  }
}

重要

将 VMD_HYDRATE_MCP_ALLOW_DIR（以操作系统路径分隔符分隔）设置为服务允许读取的目录。所有文件参数都会通过 realpath 与此允许列表进行校验 — 不在列表中的路径将被拒绝。

交互式（GUI）模式

默认情况下，服务以无头（离屏）模式驱动 VMD。若要打开一个可实时查看的真实 VMD 窗口，同时让 Claude 实时控制它，请将 VMD_HYDRATE_MCP_DISPLAY=gui 添加到服务的 env 中：

{ "mcpServers": { "vmd-hydrate": {
  "command": "uvx", "args": ["vmd-hydrate-mcp"],
  "env": { "VMD_HYDRATE_MCP_DISPLAY": "gui", "VMD_HYDRATE_MCP_ALLOW_DIR": "/path/to/data" }
}}}

然后可以提出类似 “加载 prod.gro，将水显示为点，将表面活性剂显示为 VDW，然后慢慢旋转” 的要求 — 窗口会通过 load_structure → add_representation → rotate_view 实时更新。（需要本地桌面会话；两种模式由同一个 Tcl 套接字驱动。）

MCP 工具

工具	用途	后端
vmd_status	VMD 版本 + 实时会话中加载的分子	VMD
load_structure	加载结构/轨迹（返回 molid）	VMD
list_molecules	列出已加载的分子	VMD
set_representation	设置分子的样式/颜色/材质/选择（替换现有表示）	VMD
add_representation	添加另一种表示（多表示视图）	VMD
clear_representations	移除所有表示	VMD
rotate_view / zoom_view / reset_view	实时相机控制（GUI 模式下可见）	VMD
render	当前视图的无头 PNG 图像	VMD + Tachyon
resolve_selection	选择的原子数量（可发现 .gro 文件的 0 原子陷阱）	MDAnalysis
measure_geometry	按原子索引测量距离 / 角度 / 二面角	MDAnalysis
radius_of_gyration	选择对象的回转半径 Rg	MDAnalysis
hydrate_order_params	F3 + F4 水有序参数	NumPy
hbond_network	水的氢键网络 + 配位数	NumPy
identify_cages	笼的数量（5¹²/5¹²6⁴/…）+ sI/sII/sH 结构	NumPy
render_cages	笼的照片级渲染（AO+阴影、正交投影）；可按提示词筛选 / 重着色 / 突出显示笼	VMD + NumPy

用法

1. 分析轨迹帧中的水合物有序度

Compute the F3/F4 order parameters for hydrate.gro

返回 f4_overall、f3_overall、水分子数量以及通俗易懂的解释（晶态 / 类水合物 / 液态 / 冰）。

2. 渲染结构

Load hydrate.gro, show the water oxygens as VDW spheres, and render it

使用 CPU Tachyon 以无头方式渲染，生成内嵌 PNG 图像。

3. 检查氢键网络

Build the water hydrogen-bond network for hydrate.gro at frame 0

返回氢键数量和平均配位数（结构良好的笼形水合物约为 4）。

4. 根据提示词设置水合物笼的样式

Load hydrate.gro and show only the sII large cages in magenta with emphasized width

渲染仅包含品红色 5¹²6⁴ 笼且边缘更粗的照片级正交图像 — MCP 会将其映射为 render_cages(cage_types=["51264"], highlight_color="magenta", emphasis=True)。省略筛选条件后，所有笼都会以各自的调色板颜色绘制（5¹²=青色，5¹²6⁴=红色，…）。

它真的能驱动 VMD 吗？

是的——只需运行一条命令即可验证。examples/verify.py 会在附带的 sII CO₂ 水合物示例上运行与 MCP 服务对外提供的相同代码：它会检测真实的 VMD 二进制文件、识别笼体，并在无头模式下渲染。

python examples/verify.py

预期输出：

[1] VMD found : /Applications/VMD2b1.app/.../vmd_MACOSXARM64
    ping      : pong 2.0b1 MACOSXARM64
[2] Identifying cages in a real sII CO2 hydrate (1088 waters)...
    cage counts : {'51264': 60, '512': 128}
    structure   : sII  (confidence 0.93)
    F4 order    : 0.965  (highly ordered (crystalline hydrate / ice-like))
[3] Rendering cages headlessly (blue = 5^12, red = 5^12 6^4)...
    saved       : examples/output/cages.png (362495 bytes)
OK — vmd-hydrate-mcp drove VMD and identified the cages above.

下方图像是由该流程生成的真实、未经修饰的 VMD 渲染图（并非插图）：

sII 晶体 — 按类型为笼体着色（青色 5¹²，红色 5¹²6⁴），由 Tachyon 生成的照片级渲染

单个 5¹² 十二面体，跨 PBC 展开（环境光遮蔽 + 阴影）

顶部的演示视频由此类帧拼接而成——参见 video/build_frames.py（驱动 VMD）和 video/remotion/（Remotion 合成）。运行 python video/build_frames.py && cd video/remotion && npm i && npm run gif 即可重新生成。

工作原理

  [.gro / .xtc / LAMMPS dump]
            |
            v
     MCP client (Claude)  --stdio-->  vmd-hydrate-mcp (FastMCP)
                                          |            |
                          numbers  <------+            +------>  visualization
                     MDAnalysis + NumPy                     persistent VMD session
                   (F3/F4, H-bonds, Rg)                    (Tcl socket, 127.0.0.1)
                          |                                         |
                          v                                         v
                  structured JSON                         Tachyon --> PNG image

数值科学计算在 Python 中运行（无需显示器，可在 CI 中进行单元测试）。可视化与渲染在长期运行、受令牌保护的 VMD 进程中执行。两者的单位不会混用：水合物计算使用纳米，VMD/MDAnalysis 测量值使用 Ångström。

要求

依赖项	必需	用途
VMD 2.0b1 或 1.9.4+	用于可视化/渲染	可视化引擎
Python 3.10+	是	服务
mcp	是	Model Context Protocol SDK
MDAnalysis（[mda]）	用于测量/选择	支持拓扑感知的加载
sips / ImageMagick / Pillow	用于渲染	TGA→PNG 转换

警告

在 macOS 上，VMD 以 .app 形式提供，其 CLI 二进制文件位于应用包内。如果 vmd 不在你的 PATH 中，请将 VMD_BIN 设为该二进制文件的路径（例如 /Applications/VMD*.app/Contents/vmd*/vmd_MACOSXARM64）。纯水合物/测量工具无需 VMD 即可运行。

参与贡献

1. Fork 仓库并创建分支（git checkout -b feature/x）。
2. 运行 uv pip install -e ".[dev,mda]"，并确保 pytest 全部通过（科学计算测试无需 VMD）。
3. 提交、推送并创建 PR。发现 Bug？请提交 issue。

许可证

MIT — 参见 LICENSE。