vmd-mcp: Control en lenguaje sencillo de VMD2 mediante Claude MCP

Autor: Omar Arias-Gaguancela, PhD Afiliaciones: SciLearningWorkshops LLC

¿Qué es vmd-mcp?

vmd-mcp es un servidor del Protocolo de Contexto de Modelo (MCP) que le otorga a Claude control directo y programático sobre VMD2 (Visual Molecular Dynamics). En lugar de escribir scripts en Tcl o navegar por la interfaz gráfica de VMD, describes lo que quieres en inglés sencillo y Claude se encarga del resto: cargar estructuras, configurar representaciones, medir distancias, calcular RMSD, renderizar imágenes y más.

Por qué es importante para los biólogos computacionales

El análisis de dinámica molecular es un cuello de botella: generar la simulación está cada vez más automatizado, pero interpretarla aún exige conocimientos expertos en scripts de Tcl, la interfaz gráfica de VMD y herramientas de línea de comandos. vmd-mcp cierra esa brecha.

Con esta herramienta, un investigador puede pasar de un archivo de trayectoria a figuras de calidad de publicación y mediciones cuantitativas en una sola conversación, sin necesidad de conocimientos de Tcl. También reduce la barrera para los estudiantes y aprendices que ingresan al campo, permitiéndoles centrarse en la biología en lugar de en la sintaxis del software. El diseño centrado en la seguridad (listas de permitidos de rutas, validación de comandos Tcl) lo hace seguro para implementar en entornos informáticos compartidos o educativos.

Características clave

• 23 herramientas MCP que cubren carga de estructuras, navegación de trayectorias, representaciones, mediciones, renderizado y paso directo de Tcl

• Interfaz de lenguaje natural: pídele a Claude que visualice una proteína, mida una distancia o calcule el RMSD en lenguaje sencillo

• Modo de subproceso: inicia y controla VMD2 de forma invisible (headless) en Windows sin necesidad de scripts manuales en Tcl

• Diseño centrado en la seguridad: todas las rutas de archivo se validan contra una lista de permitidos configurable; los comandos Tcl se desinfectan para bloquear operaciones peligrosas (exec, open, file, socket, etc.)

• Nativo de Windows: incluye la corrección de subproceso CREATE_NO_WINDOW para que no aparezcan ventanas de consola dispersas durante la operación

• Modo socket: opcionalmente conéctate a una instancia de VMD en ejecución previa en localhost:5555

• Servidor VMD simulado: prueba el flujo de trabajo completo sin tener VMD instalado usando mock_vmd.py

• Recursos MCP: Claude puede consultar el estado de VMD en vivo (vmd://status, vmd://molecules, vmd://selections-guide) antes de emitir comandos

Requisitos

Instalación

1. Clonar el repositorio

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

2. Crear un entorno virtual (Recomendado)

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

3. Instalar dependencias

pip install -r requirements.txt

4. Verificar que VMD2 esté instalado

El servidor espera VMD2 en:

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

Si tu ruta de instalación es diferente, abre vmd_mcp_config.json y actualiza 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"
  ]
}

Nota de seguridad: Solo se pueden cargar en VMD los archivos dentro de allowed_directories. Agrega cualquier directorio de datos adicional que necesites.

Registrar vmd-mcp con Claude Code

Opción 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"

Opción B: Configuración manual

Edita %APPDATA%\Claude\claude_desktop_config.json (aplicación de escritorio) o .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"
    }
  }
}

Reinicia Claude Code después de guardar. Deberías ver vmd-mcp listado bajo los servidores MCP conectados.

Verificar la conexión

Pregúntale a Claude: "What MCP tools are available for VMD?" Claude enumerará las 23 herramientas si el servidor está conectado correctamente.

Uso: Ejemplos de prompts en lenguaje natural

Carga de estructuras y trayectorias

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.

Visualización

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.

Navegación de trayectorias

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.

Mediciones

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.

Información de átomos

What residue and atom name is atom index 4711?

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

Renderizado y guardado

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.

Referencia rápida: Todas las herramientas

Referencia rápida de selección de átomos en 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

Solución de problemas

VMD no se inicia

Causa: La ruta vmd_executable en vmd_mcp_config.json es incorrecta. Solución: Confirma la ruta ejecutando VMD directamente:

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

Si VMD se cierra sin error, la ruta es válida. Actualiza vmd_executable en la configuración si es necesario.

La ventana de consola parpadea con cada comando

Causa: Falta la bandera de subproceso CREATE_NO_WINDOW. Solución: Esto ya está manejado en vmd_controller.py:

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

Si aún ves ventanas parpadeando, asegúrate de estar ejecutando Python 3.7+ y no haber modificado este bloque. La bandera suprime la consola oculta que Windows crea para los subprocesos hijos de forma predeterminada.

Error de bucle de eventos asyncio en Windows (ProactorEventLoop)

Causa: Python 3.8+ en Windows usa ProactorEventLoop de forma predeterminada, lo que entra en conflicto con ciertas operaciones de tubería de subprocesos utilizadas por el SDK de MCP. Solución: La siguiente política ya está establecida al inicio en vmd_mcp_server.py:

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

Si encuentras este error después de modificar el servidor, verifica que esta política esté establecida antes de asyncio.run().

Error Path outside allowed directories

Causa: El archivo que intentas cargar no está en allowed_directories. Solución: Agrega el directorio a vmd_mcp_config.json:

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

El servidor MCP no aparece en Claude Code

1. Confirma que la ruta command en la configuración de MCP apunte al intérprete de Python del .venv, no al Python del sistema.

2. Ejecuta el servidor manualmente para verificar errores de importación:

   .venv\Scripts\python.exe vmd_mcp_server.py

3. Reinicia Claude Code completamente después de cualquier cambio de configuración.

Comando Tcl bloqueado por el validador de seguridad

execute_tcl bloquea los siguientes comandos por diseño: exec, open, file, socket, package, source, load, unload, exit, quit, proc, namespace, interp, vwait. Usa las herramientas diseñadas para tal fin (load_structure, render_image, etc.) para estas operaciones en su lugar.

Pruebas sin VMD — Servidor simulado

# 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

El servidor simulado escucha en el puerto 5555 y devuelve respuestas predefinidas realistas (p. ej., DISTANCE: 3.8245, NUMFRAMES: 500), lo que permite probar el flujo de trabajo completo sin una instalación de VMD.

Citación

Si utilizas vmd-mcp en investigaciones publicadas o materiales educativos, por favor cita:

@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}
}

El DOI se registrará tras la primera versión estable. Consulta el repositorio para obtener el registro de citación actual.

También cita 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

Licencia

Licencia MIT

Copyright (c) 2026 Omar Arias-Gaguancela

Se concede permiso, de forma gratuita, a cualquier persona que obtenga una copia de este software y los archivos de documentación asociados (el "Software"), para tratar el Software sin restricciones, incluyendo, sin limitación, los derechos de uso, copia, modificación, fusión, publicación, distribución, sublicencia y/o venta de copias del Software, y para permitir a las personas a quienes se les proporcione el Software para hacerlo, sujeto a las siguientes condiciones:

El aviso de copyright anterior y este aviso de permiso se incluirán en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO PERO NO LIMITADO A LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN PROPÓSITO PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE NINGUNA RECLAMACIÓN, DAÑO U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRO TIPO, QUE SURJA DE, FUERA DE O EN CONEXIÓN CON EL SOFTWARE O EL USO U OTROS TRATOS EN EL SOFTWARE.

Acerca de

Omar Arias-Gaguancela, PhD es un biólogo computacional y educador científico enfocado en hacer que las herramientas avanzadas de simulación molecular sean accesibles para investigadores en todas las etapas de su carrera.

• SciLearningWorkshops LLC — Talleres y formación en biología estructural, simulación MD e investigación asistida por IA