vmd-mcp: Управление VMD2 на естественном языке через Claude MCP

Автор: Омар Ариас-Гагуансела, PhD Аффилиации: SciLearningWorkshops LLC

Что такое vmd-mcp?

vmd-mcp — это сервер Model Context Protocol (MCP), который предоставляет Claude прямое программное управление VMD2 (Visual Molecular Dynamics). Вместо написания Tcl-скриптов или навигации по графическому интерфейсу VMD, вы описываете свои пожелания на обычном английском языке, а Claude выполняет остальное: загружает структуры, настраивает представления, измеряет расстояния, вычисляет RMSD, визуализирует изображения и многое другое.

Почему это важно для вычислительных биологов

Анализ молекулярной динамики является «узким местом»: создание симуляций становится все более автоматизированным, но их интерпретация по-прежнему требует экспертных знаний Tcl-скриптов, графического интерфейса VMD и инструментов командной строки. vmd-mcp устраняет этот разрыв.

С помощью этого инструмента исследователь может пройти путь от файла траектории до публикационных графиков и количественных измерений в рамках одного диалога — знание Tcl не требуется. Это также снижает порог вхождения для стажеров и студентов, позволяя им сосредоточиться на биологии, а не на синтаксисе программного обеспечения. Дизайн, ориентированный на безопасность (списки разрешенных путей, проверка Tcl-команд), делает его безопасным для развертывания в общих или учебных вычислительных средах.

Ключевые особенности

• 23 инструмента MCP, охватывающих загрузку структур, навигацию по траекториям, представления, измерения, рендеринг и проброс Tcl-команд

• Интерфейс на естественном языке: попросите Claude визуализировать белок, измерить расстояние или вычислить RMSD на обычном английском

• Режим подпроцесса: запускает и управляет VMD2 в фоновом режиме (headless) на Windows без необходимости ручного написания Tcl-скриптов

• Дизайн с приоритетом безопасности — все пути к файлам проверяются по настраиваемому списку разрешенных; Tcl-команды очищаются для блокировки опасных операций (exec, open, file, socket и т.д.)

• Нативная поддержка Windows: включает исправление подпроцесса CREATE_NO_WINDOW, поэтому во время работы не появляются лишние окна консоли

• Режим сокета: опциональное подключение к уже запущенному экземпляру VMD на localhost:5555

• Mock VMD сервер: тестирование полного конвейера без установленного VMD с помощью mock_vmd.py

• Ресурсы MCP: Claude может запрашивать текущее состояние VMD (vmd://status, vmd://molecules, vmd://selections-guide) перед выполнением команд

Требования

Установка

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"
  ]
}

Примечание по безопасности: В VMD можно загружать только файлы из allowed_directories. Добавьте любые дополнительные каталоги данных, которые вам нужны.

Регистрация 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 после сохранения. Вы должны увидеть vmd-mcp в списке подключенных MCP-серверов.

Проверка подключения

Спросите Claude: "What MCP tools are available for VMD?" 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.

Краткий справочник: все инструменты

Краткий справочник по выбору атомов в 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_executable в vmd_mcp_config.json. Решение: Подтвердите путь, запустив 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 создает для дочерних подпроцессов по умолчанию.

Ошибка цикла событий asyncio в Windows (ProactorEventLoop)

Причина: Python 3.8+ в Windows по умолчанию использует 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

1. Убедитесь, что путь command в конфигурации MCP указывает на интерпретатор Python в .venv, а не на системный Python.

2. Запустите сервер вручную, чтобы проверить наличие ошибок импорта:

   .venv\Scripts\python.exe vmd_mcp_server.py

3. Полностью перезапустите Claude Code после любого изменения конфигурации.

Tcl-команда заблокирована валидатором безопасности

execute_tcl по дизайну блокирует следующие команды: exec, open, file, socket, package, source, load, unload, exit, quit, proc, namespace, interp, vwait. Вместо этого используйте специализированные инструменты (load_structure, render_image и т.д.) для этих операций.

Тестирование без VMD — Mock-сервер

# 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

Mock-сервер прослушивает порт 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

Copyright (c) 2026 Омар Ариас-Гагуансела

Настоящим предоставляется бесплатное разрешение любому лицу, получившему копию этого программного обеспечения и сопутствующей документации, использовать Программное обеспечение без ограничений, включая, помимо прочего, права на использование, копирование, изменение, объединение, публикацию, распространение, сублицензирование и/или продажу копий Программного обеспечения, а также разрешать лицам, которым предоставлено Программное обеспечение, делать это при соблюдении следующих условий:

Вышеуказанное уведомление об авторских правах и это уведомление о разрешении должны быть включены во все копии или существенные части Программного обеспечения.

ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ ГАРАНТИЯМИ ТОВАРНОЙ ПРИГОДНОСТИ, ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЕННОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ. НИ В КОЕМ СЛУЧАЕ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБЫЕ ПРЕТЕНЗИИ, УЩЕРБ ИЛИ ИНУЮ ОТВЕТСТВЕННОСТЬ, БУДЬ ТО В РЕЗУЛЬТАТЕ ДОГОВОРА, ДЕЛИКТА ИЛИ ИНОГО, ВОЗНИКШИЕ ИЗ, ИЛИ В СВЯЗИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ИСПОЛЬЗОВАНИЕМ ИЛИ ИНЫМИ ДЕЙСТВИЯМИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ.

Об авторе

Омар Ариас-Гагуансела, PhD — вычислительный биолог и преподаватель естественных наук, специализирующийся на том, чтобы сделать передовые инструменты молекулярного моделирования доступными для исследователей на всех этапах карьеры.

• SciLearningWorkshops LLC — семинары и обучение по структурной биологии, МД-симуляциям и исследованиям с использованием ИИ