vmd-mcp: Steuerung von VMD2 in natürlicher Sprache via Claude MCP

Autor: Omar Arias-Gaguancela, PhD Zugehörigkeit: SciLearningWorkshops LLC

Was ist vmd-mcp?

vmd-mcp ist ein Model Context Protocol (MCP)-Server, der Claude eine direkte, programmatische Kontrolle über VMD2 (Visual Molecular Dynamics) gibt. Anstatt Tcl-Skripte zu schreiben oder durch die GUI von VMD zu navigieren, beschreiben Sie in einfachem Englisch, was Sie tun möchten, und Claude erledigt den Rest: Strukturen laden, Darstellungen einrichten, Abstände messen, RMSD berechnen, Bilder rendern und mehr.

Warum ist das für Computerbiologen wichtig?

Die Analyse von Molekulardynamik ist ein Engpass: Die Erstellung der Simulation wird zunehmend automatisiert, aber die Interpretation erfordert immer noch Expertenwissen in Tcl-Skripting, der VMD-GUI und Befehlszeilen-Tools. vmd-mcp schließt diese Lücke.

Mit diesem Tool kann ein Forscher in einem einzigen Gespräch von der Trajektoriendatei zu publikationsreifen Abbildungen und quantitativen Messungen gelangen – ganz ohne Tcl-Kenntnisse. Es senkt auch die Hürde für Auszubildende und Studenten, die in das Feld einsteigen, und lässt sie sich auf die Biologie statt auf die Software-Syntax konzentrieren. Das sicherheitsorientierte Design (Pfad-Allowlists, Tcl-Befehlsvalidierung) macht den Einsatz in gemeinsam genutzten oder schulischen Rechenumgebungen sicher.

Hauptmerkmale

• 23 MCP-Tools für das Laden von Strukturen, Trajektorien-Navigation, Darstellungen, Messungen, Rendering und Tcl-Passthrough

• Schnittstelle in natürlicher Sprache: Bitten Sie Claude, ein Protein zu visualisieren, einen Abstand zu messen oder RMSD in einfachem Englisch zu berechnen

• Subprocess-Modus: Startet und steuert VMD2 headless unter Windows, ohne dass manuelle Tcl-Skripte erforderlich sind

• Sicherheitsorientiertes Design — alle Dateipfade werden gegen eine konfigurierbare Allowlist validiert; Tcl-Befehle werden bereinigt, um gefährliche Operationen (exec, open, file, socket usw.) zu blockieren

• Windows-nativ: Enthält den CREATE_NO_WINDOW-Subprocess-Fix, sodass während des Betriebs keine störenden Konsolenfenster erscheinen

• Socket-Modus: Optionales Verbinden mit einer bereits laufenden VMD-Instanz auf localhost:5555

• Mock VMD-Server: Testen Sie die gesamte Pipeline ohne installiertes VMD mit mock_vmd.py

• MCP-Ressourcen: Claude kann den Live-VMD-Status abfragen (vmd://status, vmd://molecules, vmd://selections-guide), bevor Befehle erteilt werden

Anforderungen

Installation

1. Repository klonen

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

2. Virtuelle Umgebung erstellen (empfohlen)

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

3. Abhängigkeiten installieren

pip install -r requirements.txt

4. VMD2-Installation überprüfen

Der Server erwartet VMD2 unter:

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

Wenn Ihr Installationspfad abweicht, öffnen Sie vmd_mcp_config.json und aktualisieren Sie 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"
  ]
}

Sicherheitshinweis: Nur Dateien innerhalb von allowed_directories können in VMD geladen werden. Fügen Sie alle weiteren benötigten Datenverzeichnisse hinzu.

Registrierung von vmd-mcp bei Claude Code

Option 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"

Option B: Manuelle Konfiguration

Bearbeiten Sie %APPDATA%\Claude\claude_desktop_config.json (Desktop-App) oder .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"
    }
  }
}

Starten Sie Claude Code nach dem Speichern neu. Sie sollten vmd-mcp unter den verbundenen MCP-Servern sehen.

Verbindung überprüfen

Fragen Sie Claude: "Welche MCP-Tools sind für VMD verfügbar?" Claude wird alle 23 Tools auflisten, wenn der Server korrekt verbunden ist.

Verwendung: Beispiele für Prompts in natürlicher Sprache

Strukturen und Trajektorien laden

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.

Visualisierung

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.

Trajektorien-Navigation

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.

Messungen

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.

Atom-Informationen

What residue and atom name is atom index 4711?

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

Rendern und Speichern

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.

Kurzübersicht: Alle Tools

VMD Atom-Selektion Kurzübersicht

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

Fehlerbehebung

VMD startet nicht

Ursache: Der Pfad vmd_executable in vmd_mcp_config.json ist falsch. Lösung: Überprüfen Sie den Pfad, indem Sie VMD direkt ausführen:

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

Wenn VMD ohne Fehler beendet wird, ist der Pfad gültig. Aktualisieren Sie vmd_executable in der Konfiguration, falls erforderlich.

Konsolenfenster blinkt bei jedem Befehl

Ursache: Fehlendes CREATE_NO_WINDOW-Subprocess-Flag. Lösung: Dies wird bereits in vmd_controller.py behandelt:

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

Wenn Sie immer noch blinkende Fenster sehen, stellen Sie sicher, dass Sie Python 3.7+ ausführen und diesen Block nicht geändert haben. Das Flag unterdrückt die versteckte Konsole, die Windows standardmäßig für Subprocess-Kinder erstellt.

asyncio Event Loop Fehler unter Windows (ProactorEventLoop)

Ursache: Python 3.8+ unter Windows verwendet standardmäßig ProactorEventLoop, was mit bestimmten Subprocess-Pipe-Operationen kollidiert, die vom MCP SDK verwendet werden. Lösung: Die folgende Richtlinie ist bereits beim Start in vmd_mcp_server.py festgelegt:

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

Wenn dieser Fehler nach dem Ändern des Servers auftritt, stellen Sie sicher, dass diese Richtlinie vor asyncio.run() festgelegt ist.

Fehler Path outside allowed directories

Ursache: Die Datei, die Sie laden möchten, befindet sich nicht in allowed_directories. Lösung: Fügen Sie das Verzeichnis zu vmd_mcp_config.json hinzu:

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

MCP-Server erscheint nicht in Claude Code

1. Bestätigen Sie, dass der command-Pfad in der MCP-Konfiguration auf den .venv Python-Interpreter zeigt, nicht auf das System-Python.

2. Führen Sie den Server manuell aus, um auf Importfehler zu prüfen:

   .venv\Scripts\python.exe vmd_mcp_server.py

3. Starten Sie Claude Code nach jeder Konfigurationsänderung vollständig neu.

Tcl-Befehl durch Sicherheits-Validator blockiert

execute_tcl blockiert konstruktionsbedingt die folgenden Befehle: exec, open, file, socket, package, source, load, unload, exit, quit, proc, namespace, interp, vwait. Verwenden Sie stattdessen die zweckgebundenen Tools (load_structure, render_image usw.) für diese Operationen.

Testen ohne VMD — Mock-Server

# 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

Der Mock-Server lauscht auf Port 5555 und gibt realistische Antworten zurück (z. B. DISTANCE: 3.8245, NUMFRAMES: 500), was ein vollständiges Testen der Pipeline ohne VMD-Installation ermöglicht.

Zitierung

Wenn Sie vmd-mcp in veröffentlichter Forschung oder Lehrmaterialien verwenden, zitieren Sie bitte:

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

Die DOI wird mit der ersten stabilen Version registriert. Überprüfen Sie das Repository auf den aktuellen Zitierdatensatz.

Zitieren Sie auch 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

Lizenz

MIT-Lizenz

Copyright (c) 2026 Omar Arias-Gaguancela

Hiermit wird jeder Person, die eine Kopie dieser Software und der zugehörigen Dokumentationsdateien (die "Software") erhält, kostenlos die Erlaubnis erteilt, uneingeschränkt mit der Software zu handeln, einschließlich der Rechte zur Nutzung, zum Kopieren, Ändern, Zusammenführen, Veröffentlichen, Verbreiten, Unterlizenzieren und/oder Verkaufen von Kopien der Software, und Personen, denen die Software zur Verfügung gestellt wird, dies unter den folgenden Bedingungen zu gestatten:

Der obige Urheberrechtshinweis und dieser Genehmigungshinweis müssen in allen Kopien oder wesentlichen Teilen der Software enthalten sein.

DIE SOFTWARE WIRD OHNE JEDE AUSDRÜCKLICHE ODER STILLSCHWEIGENDE GARANTIE BEREITGESTELLT, EINSCHLIESSLICH, ABER NICHT BESCHRÄNKT AUF DIE GARANTIE DER MARKTGÄNGIGKEIT, DER EIGNUNG FÜR EINEN BESTIMMTEN ZWECK UND DER NICHTVERLETZUNG VON RECHTEN DRITTER. IN KEINEM FALL SIND DIE AUTOREN ODER URHEBERRECHTSINHABER FÜR ANSPRÜCHE, SCHÄDEN ODER ANDERE HAFTUNGEN HAFTBAR, SEI ES AUS VERTRAG, UNERLAUBTER HANDLUNG ODER ANDERWEITIG, DIE SICH AUS, AUS ODER IN VERBINDUNG MIT DER SOFTWARE ODER DER NUTZUNG ODER ANDEREN GESCHÄFTEN MIT DER SOFTWARE ERGEBEN.

Über

Omar Arias-Gaguancela, PhD ist Computerbiologe und Wissenschaftspädagoge mit dem Schwerpunkt, fortgeschrittene Molekularsimulationswerkzeuge für Forscher in allen Karrierestufen zugänglich zu machen.

• SciLearningWorkshops LLC — Workshops und Training in Strukturbiologie, MD-Simulation und KI-gestützter Forschung