vmd-mcp：通过 Claude MCP 使用自然语言控制 VMD2

Python 3.11+ License: MIT Platform: Windows

作者： Omar Arias-Gaguancela, PhD 所属机构： SciLearningWorkshops LLC

什么是 vmd-mcp？

vmd-mcp 是一个模型上下文协议 (MCP) 服务器，它赋予 Claude 对 VMD2 (Visual Molecular Dynamics) 的直接程序化控制能力。无需编写 Tcl 脚本或操作 VMD 的图形界面，你只需用简单的英语描述你的需求，Claude 就会处理剩下的工作，包括加载结构、设置表现形式、测量距离、计算 RMSD、渲染图像等。

它对计算生物学家的意义

分子动力学分析是一个瓶颈：模拟的生成正日益自动化，但对其进行“解读”仍然需要 Tcl 脚本、VMD 图形界面和命令行工具方面的专业知识。vmd-mcp 弥补了这一差距。

有了这个工具，研究人员可以在单次对话中完成从轨迹文件到出版级图片和定量测量的工作——无需任何 Tcl 知识。它还降低了初学者和学生进入该领域的门槛，让他们能够专注于生物学本身而非软件语法。其注重安全的设计（路径白名单、Tcl 命令验证）使其可以安全地部署在共享或教学计算环境中。

主要功能

23 个 MCP 工具：涵盖结构加载、轨迹导航、表现形式、测量、渲染和 Tcl 透传
自然语言接口：要求 Claude 以简单的英语可视化蛋白质、测量距离或计算 RMSD
子进程模式：在 Windows 上以无头模式启动并控制 VMD2，无需手动编写 Tcl 脚本
安全优先设计：所有文件路径均根据可配置的白名单进行验证；Tcl 命令经过清理，以阻止危险操作（如 exec、open、file、socket 等）
Windows 原生支持：包含 CREATE_NO_WINDOW 子进程修复，确保操作过程中不会出现杂乱的控制台窗口
Socket 模式：可选择连接到 localhost:5555 上预先运行的 VMD 实例
模拟 VMD 服务器：使用 mock_vmd.py 在未安装 VMD 的情况下测试完整流程
MCP 资源：Claude 可以在发出命令前查询实时的 VMD 状态（vmd://status、vmd://molecules、vmd://selections-guide）

要求

依赖	版本	备注
VMD2	2.x	安装到默认路径或更新 `vmd_mcp_config.json`
Python	3.11+	Windows 上使用 `asyncio` 子进程功能所必需
Claude Code	最新版	CLI、桌面应用或 IDE 扩展
`mcp`	≥ 1.0.0	模型上下文协议 SDK
`pydantic`	≥ 2.0.0	工具输入的数据验证

安装

1. 克隆仓库

git clone https://github.com/oarias/vmd-mcp.git
cd vmd-mcp

2. 创建虚拟环境（推荐）

python -m venv .venv
.venv\Scripts\Activate.ps1

3. 安装依赖

pip install -r requirements.txt

4. 验证 VMD2 是否已安装

服务器预期 VMD2 位于：

C:\Program Files\University of Illinois\VMD2\vmd.exe

如果你的安装路径不同，请打开 vmd_mcp_config.json 并更新 vmd_executable：

{
  "vmd_executable": "C:\\Program Files\\University of Illinois\\VMD2\\vmd.exe",
  "communication_mode": "subprocess",
  "socket_host": "localhost",
  "socket_port": 5555,
  "socket_timeout": 10.0,
  "subprocess_args": ["-dispdev", "win"],
  "allowed_directories": [
    "C:\\Users\\YourName\\Desktop",
    "C:\\Users\\YourName\\Documents",
    "C:\\Users\\YourName\\Downloads"
  ]
}

安全提示： 只有 allowed_directories 中的文件才能加载到 VMD 中。请添加你需要的任何额外数据目录。

将 vmd-mcp 注册到 Claude Code

选项 A：Claude Code CLI

claude mcp add vmd-mcp `
  --command "C:\Users\YourName\Desktop\vmd-mcp\.venv\Scripts\python.exe" `
  --args "C:\Users\YourName\Desktop\vmd-mcp\vmd_mcp_server.py"

选项 B：手动配置

编辑 %APPDATA%\Claude\claude_desktop_config.json（桌面应用）或 .claude.json（CLI）：

{
  "mcpServers": {
    "vmd-mcp": {
      "command": "C:\\Users\\YourName\\Desktop\\vmd-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\YourName\\Desktop\\vmd-mcp\\vmd_mcp_server.py"],
      "cwd": "C:\\Users\\YourName\\Desktop\\vmd-mcp"
    }
  }
}

保存后重启 Claude Code。你应该能在已连接的 MCP 服务器列表中看到 vmd-mcp。

验证连接

询问 Claude：“What MCP tools are available for VMD?”（VMD 有哪些可用的 MCP 工具？）如果服务器连接正确，Claude 将列出所有 23 个工具。

使用方法：自然语言提示示例

加载结构和轨迹

Load C:\Users\me\Desktop\project\protein.pdb into VMD.

Load MtFAAH_1MAG16.pdb as the topology and MtFAAH_1MAG16_10ns_merged.dcd
as the trajectory.

可视化

Show the protein as NewCartoon colored by secondary structure,
and display the ligand as Licorice with CPK coloring.

Set the background to white and reset the camera.

Add a VDW surface for all water molecules within 5 Å of the active site.

轨迹导航

How many frames are in molecule 0?

Go to frame 500 and take a snapshot — save it to C:\Users\me\Desktop\frame500.tga.

Play the trajectory from frame 0 to 1000 at speed 5.

测量

Measure the distance between atom 1042 and atom 2318 in the current frame.

What is the angle formed by atoms 101, 205, and 310?

Compute the backbone RMSD relative to frame 0 across all frames.

原子信息

What residue and atom name is atom index 4711?

List all atoms in the selection "resname MAG" — show residue IDs and atom names.

渲染和保存

Render a high-quality Tachyon image to C:\Users\me\Desktop\figure1.tga.

Save the current VMD session to C:\Users\me\Desktop\session.vmd.

快速参考：所有工具

自然语言	工具
"Load a PDB file"	`load_structure`
"Load topology + trajectory"	`load_trajectory`
"What molecules are loaded?"	`list_loaded_molecules`
"Remove molecule 2"	`delete_molecule`
"Set the representation to NewCartoon"	`set_representation`
"Add a Licorice layer"	`add_representation`
"Remove representation 0"	`delete_representation`
"Change background color"	`set_background_color`
"Reset the view"	`reset_view`
"How many frames?"	`get_frame_count`
"Jump to frame N"	`go_to_frame`
"Play the trajectory"	`play_trajectory`
"Stop the animation"	`stop_playback`
"Measure distance between two atoms"	`measure_distance`
"Measure angle at three atoms"	`measure_angle`
"Compute RMSD"	`measure_rmsd`
"Show atom info for a selection"	`get_atom_info`
"Render an image"	`render_image`
"Save the VMD session"	`save_session`
"Run this Tcl command"	`execute_tcl`

VMD 原子选择快速参考

protein                        all protein atoms
backbone                       N, CA, C, O atoms
resname LIG                    residue named LIG
resid 45                       residue number 45
resid 45 to 102                residue range
chain A                        chain A
name CA                        alpha carbons only
within 5 of resname LIG        atoms within 5 Å of ligand
protein and not water          protein excluding solvent

故障排除

VMD 无法启动

原因： vmd_mcp_config.json 中的 vmd_executable 路径不正确。 修复： 通过直接运行 VMD 来确认路径：

& "C:\Program Files\University of Illinois\VMD2\vmd.exe" -dispdev none -e nul

如果 VMD 正常启动且无错误，则路径有效。如有必要，请在配置中更新 vmd_executable。

每个命令都会闪烁控制台窗口

原因： 缺少 CREATE_NO_WINDOW 子进程标志。 修复： 这已在 vmd_controller.py 中处理：

if hasattr(subprocess, "CREATE_NO_WINDOW"):
    kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW

如果你仍然看到闪烁的窗口，请确保你运行的是 Python 3.7+ 且未修改此代码块。该标志默认抑制了 Windows 为子进程创建的隐藏控制台。

Windows 上的 `asyncio` 事件循环错误 (`ProactorEventLoop`)

原因： Windows 上的 Python 3.8+ 默认使用 ProactorEventLoop，这与 MCP SDK 使用的某些子进程管道操作冲突。 修复： 以下策略已在 vmd_mcp_server.py 的启动时设置：

import asyncio, sys
if sys.platform == "win32":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())

如果你在修改服务器后遇到此错误，请验证此策略是否在 asyncio.run() 之前设置。

`Path outside allowed directories` 错误

原因： 你尝试加载的文件不在 allowed_directories 中。 修复： 将该目录添加到 vmd_mcp_config.json：

"allowed_directories": [
  "C:\\Users\\YourName\\Desktop",
  "C:\\Users\\YourName\\Projects\\my_md_data"
]

MCP 服务器未出现在 Claude Code 中

确认 MCP 配置中的 command 路径指向 .venv Python 解释器，而不是系统 Python。
手动运行服务器以检查导入错误：
```
.venv\Scripts\python.exe vmd_mcp_server.py
```
在进行任何配置更改后，请彻底重启 Claude Code。

Tcl 命令被安全验证器拦截

execute_tcl 默认拦截以下命令：exec, open, file, socket, package, source, load, unload, exit, quit, proc, namespace, interp, vwait。请改用专门的工具（load_structure, render_image 等）来执行这些操作。

无需 VMD 进行测试 — 模拟服务器

# Terminal 1 — start the mock VMD server
python mock_vmd.py

# Terminal 2 — start the MCP server (connects to the mock)
python vmd_mcp_server.py

模拟服务器在 5555 端口监听并返回真实的预设响应（例如 DISTANCE: 3.8245, NUMFRAMES: 500），允许在未安装 VMD 的情况下测试完整流程。

引用

如果你在已发表的研究或教育材料中使用 vmd-mcp，请引用：

@software{arias2026vmdmcp,
  author    = {Arias-Gaguancela, Omar},
  title     = {vmd-mcp: Plain Language Control of VMD2 via Claude MCP},
  year      = {2026},
  publisher = {GitHub},
  url       = {https://github.com/oarias/vmd-mcp},
  doi       = {10.5281/zenodo.XXXXXXX}
}

DOI 将在首次稳定版本发布时注册。请查看仓库以获取当前的引用记录。

同时引用 VMD：

Humphrey, W., Dalke, A. and Schulten, K. (1996). VMD — Visual Molecular Dynamics. Journal of Molecular Graphics, 14, 33–38. https://doi.org/10.1016/0263-7855(96)00018-5

许可证

MIT 许可证

特此免费授予任何获得本软件及相关文档文件（“软件”）副本的人员无限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售本软件副本的权利，并允许向其提供本软件的人员在遵守以下条件的前提下这样做：

本软件按“原样”提供，不提供任何形式的明示或暗示保证，包括但不限于对适销性、特定用途的适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对因本软件或本软件的使用或其他交易而引起的任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权诉讼还是其他诉讼中。

关于

Omar Arias-Gaguancela, PhD 是一位计算生物学家和科学教育家，致力于让各阶段的研究人员都能使用先进的分子模拟工具。

SciLearningWorkshops LLC — 提供结构生物学、MD 模拟和 AI 辅助研究方面的研讨会和培训

vmd-mcp

vmd-mcp：通过 Claude MCP 使用自然语言控制 VMD2

什么是 vmd-mcp？

它对计算生物学家的意义

主要功能

要求

安装

1. 克隆仓库

2. 创建虚拟环境（推荐）

3. 安装依赖

4. 验证 VMD2 是否已安装

将 vmd-mcp 注册到 Claude Code

选项 A：Claude Code CLI

选项 B：手动配置

验证连接

使用方法：自然语言提示示例

加载结构和轨迹

可视化

轨迹导航

测量

原子信息

渲染和保存

快速参考：所有工具

VMD 原子选择快速参考

故障排除

VMD 无法启动

每个命令都会闪烁控制台窗口

Windows 上的 `asyncio` 事件循环错误 (`ProactorEventLoop`)

`Path outside allowed directories` 错误

MCP 服务器未出现在 Claude Code 中

Tcl 命令被安全验证器拦截

无需 VMD 进行测试 — 模拟服务器

引用

许可证

关于

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

vmd-mcp：通过 Claude MCP 使用自然语言控制 VMD2

什么是 vmd-mcp？

它对计算生物学家的意义

主要功能

要求

安装

1. 克隆仓库

2. 创建虚拟环境（推荐）

3. 安装依赖

4. 验证 VMD2 是否已安装

将 vmd-mcp 注册到 Claude Code

选项 A：Claude Code CLI

选项 B：手动配置

验证连接

使用方法：自然语言提示示例

加载结构和轨迹

可视化

轨迹导航

测量

原子信息

渲染和保存

快速参考：所有工具

VMD 原子选择快速参考

故障排除

VMD 无法启动

每个命令都会闪烁控制台窗口

Windows 上的 asyncio 事件循环错误 (ProactorEventLoop)

Path outside allowed directories 错误

MCP 服务器未出现在 Claude Code 中

Tcl 命令被安全验证器拦截

无需 VMD 进行测试 — 模拟服务器

引用

许可证

关于

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

Windows 上的 `asyncio` 事件循环错误 (`ProactorEventLoop`)

`Path outside allowed directories` 错误