vmd-mcp: Plain Language Control of VMD2 via Claude MCP

Author: Omar Arias-Gaguancela, PhD
Affiliations: SciLearningWorkshops LLC

What Is vmd-mcp?

vmd-mcp is a Model Context Protocol (MCP) server that gives Claude direct, programmatic control over VMD2 (Visual Molecular Dynamics). Instead of writing Tcl scripts or navigating VMD's GUI, you describe what you want in plain English and Claude handles the rest, loading structures, setting up representations, measuring distances, computing RMSD, rendering images, and more.

Why It Matters for Computational Biologists

Molecular dynamics analysis is a bottleneck: generating the simulation is increasingly automated, but interpreting it still demands expert knowledge of Tcl scripting, VMD's GUI, and command-line tooling. vmd-mcp closes that gap.

With this tool, a researcher can go from trajectory file to publication-quality figures and quantitative measurements in a single conversation — no Tcl knowledge required. It also lowers the barrier for trainees and students entering the field, letting them focus on biology rather than software syntax. The security-conscious design (path allowlists, Tcl command validation) makes it safe to deploy in shared or instructional computing environments.

Key Features

• 23 MCP tools covering structure loading, trajectory navigation, representations, measurements, rendering, and Tcl passthrough

• Natural language interface : ask Claude to visualize a protein, measure a distance, or compute RMSD in plain English

• Subprocess mode : launches and controls VMD2 headlessly on Windows with no manual Tcl scripting needed

• Security-first design — all file paths are validated against a configurable allowlist; Tcl commands are sanitized to block dangerous operations (exec, open, file, socket, etc.)

• Windows-native : includes the CREATE_NO_WINDOW subprocess fix so no stray console windows appear during operation

• Socket mode: optionally connect to a pre-running VMD instance on localhost:5555

• Mock VMD server : test the full pipeline without VMD installed using mock_vmd.py

• MCP Resources : Claude can query live VMD state (vmd://status, vmd://molecules, vmd://selections-guide) before issuing commands

Requirements

Installation

1. Clone the Repository

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

2. Create a Virtual Environment (Recommended)

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

3. Install Dependencies

pip install -r requirements.txt

4. Verify VMD2 Is Installed

The server expects VMD2 at:

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

If your installation path differs, open vmd_mcp_config.json and update 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"
  ]
}

Security note: Only files inside allowed_directories can be loaded into VMD. Add any additional data directories you need.

Registering vmd-mcp with 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: Manual Config

Edit %APPDATA%\Claude\claude_desktop_config.json (desktop app) or .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"
    }
  }
}

Restart Claude Code after saving. You should see vmd-mcp listed under connected MCP servers.

Verify the Connection

Ask Claude: "What MCP tools are available for VMD?"
Claude will enumerate all 23 tools if the server is connected correctly.

Usage: Example Natural Language Prompts

Loading Structures and Trajectories

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.

Visualization

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.

Trajectory 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.

Measurements

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 Information

What residue and atom name is atom index 4711?

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

Rendering and Saving

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.

Quick Reference: All Tools

VMD Atom Selection Quick Reference

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

Troubleshooting

VMD Does Not Launch

Cause: vmd_executable path in vmd_mcp_config.json is incorrect.
Fix: Confirm the path by running VMD directly:

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

If VMD exits without error, the path is valid. Update vmd_executable in the config if needed.

Console Window Flashes on Every Command

Cause: Missing CREATE_NO_WINDOW subprocess flag.
Fix: This is already handled in vmd_controller.py:

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

If you still see flashing windows, ensure you are running Python 3.7+ and have not modified this block. The flag suppresses the hidden console Windows creates for subprocess children by default.

asyncio Event Loop Error on Windows (ProactorEventLoop)

Cause: Python 3.8+ on Windows defaults to ProactorEventLoop, which conflicts with certain subprocess pipe operations used by the MCP SDK.
Fix: The following policy is already set at startup in vmd_mcp_server.py:

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

If you encounter this error after modifying the server, verify this policy is set before asyncio.run().

Path outside allowed directories Error

Cause: The file you are trying to load is not in allowed_directories.
Fix: Add the directory to vmd_mcp_config.json:

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

MCP Server Not Appearing in Claude Code

1. Confirm the command path in the MCP config points to the .venv Python interpreter, not the system Python.

2. Run the server manually to check for import errors:

   .venv\Scripts\python.exe vmd_mcp_server.py

3. Restart Claude Code completely after any configuration change.

Tcl Command Blocked by Security Validator

execute_tcl blocks the following commands by design: exec, open, file, socket, package, source, load, unload, exit, quit, proc, namespace, interp, vwait. Use the purpose-built tools (load_structure, render_image, etc.) for these operations instead.

Testing Without 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

The mock server listens on port 5555 and returns realistic canned responses (e.g., DISTANCE: 3.8245, NUMFRAMES: 500), allowing full pipeline testing without a VMD installation.

Citation

If you use vmd-mcp in published research or educational materials, please cite:

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

The DOI will be registered upon first stable release. Check the repository for the current citation record.

Also cite 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

License

MIT License

Copyright (c) 2026 Omar Arias-Gaguancela

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

About

Omar Arias-Gaguancela, PhD is a computational biologist and science educator focused on making advanced molecular simulation tools accessible to researchers at all career stages.

• SciLearningWorkshops LLC — Workshops and training in structural biology, MD simulation, and AI-assisted research