vmd-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vmd-mcp Load 1UBQ.pdb, compute RMSD, and render a NewCartoon image at 1200x900."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🔬 vmd-mcp
Drive VMD headlessly from any MCP client.
Analyse structures & trajectories (RMSD, radius of gyration, SASA, atom selections) and ray-trace publication-quality images with no display — all through the Model Context Protocol.
Why
VMD is the standard tool for molecular visualisation and trajectory analysis, but its power
lives behind a GUI and a Tcl console. vmd-mcp runs VMD in text mode, turns the common
analyses and rendering into clean MCP tools, and parses the results back into structured data —
so an LLM agent can measure an RMSD curve or render a labelled cartoon without a display,
without you writing a line of Tcl.
Related MCP server: ChimeraX MCP Server
Features
Headless analysis — molecule summaries, atom-selection counts, RMSD, RMSF, radius of gyration, SASA, selection distances, and contact pairs.
Headless rendering — ray-traces images with VMD's built-in Tachyon and saves PNG, no X11 / display required. Choose explicit render controls or curated presets.
MCP-native guidance — resources expose capabilities, recent outputs, and example recipes; prompts help clients render molecules, analyze trajectories, and debug VMD failures.
Safer local defaults — structure inputs must exist, render outputs stay under
VMD_MCP_ROOTby default, high-risk tool inputs are bounded, and MCP tool annotations mark read-only, write, and escape-hatch behavior.Hybrid tool design — typed helpers for common jobs plus a generic
run_tclescape hatch that runs any VMD Tcl and returns bounded output plus your@@VMDMCP@@-tagged results.Robust in non-interactive sessions — works around VMD's
-eofexit/stdin anddisplay resizequirks that otherwise break headless runs (see How it works).Zero-config discovery — finds VMD on
PATHor in macOS.appbundles (override withVMD_BIN).
Tools
Category | Tool | Purpose |
Introspect |
| VMD version + resolved launcher path |
| Atoms, frames, protein/water/chain/residue counts | |
| Count atoms matching a VMD selection | |
Analyse |
| Per-frame R_gyr + min/max/mean |
| Per-frame RMSD vs a reference frame (optional alignment) | |
| Per-atom RMSF across a trajectory | |
| Per-frame solvent-accessible surface area | |
| Center-to-center distance between two selections | |
| Atom-index contact pairs between selections | |
Render |
| Headless Tachyon ray-trace → PNG |
| Curated render presets for common figures | |
Escape hatch |
| Any VMD Tcl script (with marker parsing) |
Resources & prompts
Type | Name / URI | Purpose |
Resource |
| Tool categories, allowed render options, presets, safety defaults |
Resource |
| Recent files below |
Resource |
| Compact example workflows |
Prompt |
| Safe render workflow using |
Prompt |
| RMSD/RMSF/R_gyr/SASA trajectory workflow |
Prompt |
| Triage path for path, selection, rendering, and Tcl errors |
Requirements
VMD installed and runnable (GUI build is fine; it is used in
-dispdev textmode).Python ≥ 3.10.
PNG conversion: macOS
sips(built in) or ImageMagick. Without either, renders are saved as.tga.An MCP client (e.g. Claude Code or Claude Desktop).
Install & run
# Run straight from GitHub with uv — no global install needed
uvx --from git+https://github.com/Alierkn/vmd-mcp vmd-mcppipx install git+https://github.com/Alierkn/vmd-mcp
# or
pip install git+https://github.com/Alierkn/vmd-mcp
vmd-mcp # starts the stdio serverConnect it to your MCP client
Claude Code
claude mcp add vmd --scope user -- \
uvx --from git+https://github.com/Alierkn/vmd-mcp vmd-mcpCheck: claude mcp list → vmd: … ✔ Connected.
Claude Desktop
{
"mcpServers": {
"vmd": {
"command": "uvx",
"args": ["--from", "git+https://github.com/Alierkn/vmd-mcp", "vmd-mcp"],
"env": { "VMD_BIN": "/Applications/VMD2b1.app/Contents/MacOS/startup.command" }
}
}
}Configuration
Env var | Default | Meaning |
| auto ( | Path to the VMD launcher |
|
| Where rendered images / scratch are written |
| unset / | Set to |
Example prompts
"Load
bpti.pdb, tell me how many residues and chains it has, then render a Structure-colored NewCartoon at 1200×900 and save it asbpti.png."
"For
topol.tpr+md.xtc, compute the CA-RMSD over the trajectory aligned to frame 0, and report min / max / mean."
"Using
examples/sample.pdb, run the bundled VMD smoke workflow and rendersample.pngwith theatomistic_linespreset."
How it works
Each tool generates a small Tcl script and runs vmd -dispdev text -e script.tcl. Results are
emitted with a @@VMDMCP@@ key=value marker that the server parses into structured data.
Two headless-specific gotchas are handled for you:
-eofexit+ non-tty stdin would make VMD exit before a long render finishes — so the server relies on a trailingquitandstdin=DEVNULLinstead.display resizeis unreliable without a real display — so render resolution is set via the-size W Hcommand-line flag.
Images are ray-traced with render TachyonInternal (built-in, no external renderer needed) and
converted TGA → PNG via macOS sips, ImageMagick magick, or ImageMagick convert when
available. If no converter is present, the .tga is kept.
Safety model
vmd-mcp is a local automation server, not a remote multi-user service. Typed tools validate
paths, dimensions, timeouts, selections, render methods, and color modes before launching VMD.
render_image writes below VMD_MCP_ROOT unless VMD_MCP_ALLOW_ABSOLUTE_OUTPUTS=1 is set.
The run_tcl tool intentionally remains an escape hatch for advanced VMD workflows. It is marked
as a destructive MCP tool, capped by timeout and output size, and should only be used with Tcl you
trust.
Development
git clone https://github.com/Alierkn/vmd-mcp && cd vmd-mcp
uv sync --extra dev
uv run pytest # VMD-dependent tests auto-skip if VMD is absent
RUN_VMD_INTEGRATION=1 uv run pytest -m integration
uv run python scripts/smoke_vmd.py
uv run ruff check .
uv build
uvx twine check dist/*See CONTRIBUTING.md.
Related
gromacs-mcp — companion MCP server that runs GROMACS simulations. Pair them: simulate with GROMACS, then analyse & visualise with VMD.
License
MIT © Ali Erkan Ocaklı
Available Tools
12 toolscontactsARead-onlyIdempotent
Find atom-index contact pairs between two selections at one frame.
cutoff is in Angstrom. The total contact count is always returned; the
explicit pairs list is clipped to max_pairs to keep MCP responses
bounded.
Inputs: structure (required), selection1 (required), frame, cutoff, +3 more.
count_atomsBRead-onlyIdempotent
Count atoms matching a VMD atom-selection expression
(e.g. "protein and name CA", "resname LIG", "within 5 of protein").
Inputs: selection (required), structure (required), trajectory.
distanceARead-onlyIdempotent
Distance between the centers of two atom selections.
By default the distance is measured at one frame. Set all_frames=True to
return a per-frame series for a trajectory.
Inputs: structure (required), selection1 (required), selection2 (required), frame, +3 more.
molecule_infoARead-onlyIdempotent
Load a structure (and optional trajectory) and report a summary: total atoms, number of frames, protein/water/backbone atom counts, and the number of distinct chains and residues.
Inputs: structure (required), trajectory.
radius_of_gyrationBRead-onlyIdempotent
Radius of gyration (nm-scale, in VMD's Angstrom units) of a selection, computed for every frame. Returns a per-frame series plus min/max/mean.
Inputs: structure (required), selection, trajectory, mass_weighted.
render_imageADestructive
Ray-trace a molecular image HEADLESSLY with VMD's built-in Tachyon and save it as PNG (no display needed).
representation is one of the supported VMD draw methods; coloring is
one of the supported VMD color methods. The image is written under
VMD_MCP_ROOT by default. Absolute output paths are rejected unless
VMD_MCP_ALLOW_ABSOLUTE_OUTPUTS=1 is set.
Inputs: structure (required), frame, width, height, +6 more.
render_presetCDestructive
Render a molecule using a curated publication-oriented visual preset.
Presets reduce brittle representation/coloring choices while still allowing
a custom atom selection when needed.
Inputs: structure (required), frame, width, height, +4 more.
rmsdARead-onlyIdempotent
RMSD of a selection across a trajectory relative to a reference frame.
With align=True each frame is first least-squares fitted onto the
reference (rigid-body alignment) before measuring RMSD. Returns a per-frame
series plus min/max/mean (Angstrom).
Inputs: structure (required), trajectory (required), align, selection, +1 more.
rmsfARead-onlyIdempotent
Per-atom root-mean-square fluctuation (RMSF) across a trajectory.
Returns one row per selected atom plus min/max/mean RMSF in Angstrom. Use
selections such as "protein and name CA" for compact per-residue traces.
Inputs: structure (required), trajectory (required), selection.
run_tclADestructive
Run an ARBITRARY VMD Tcl script headlessly and return its combined
stdout/stderr plus any parsed @@VMDMCP@@ marker lines.
Emit results from your script with: puts "@@VMDMCP@@ key=value ...".
Use this for any analysis not covered by a dedicated tool (measure hbonds,
measure contacts, custom per-residue loops, cluster analysis, ...).
End the script with quit.
Inputs: script (required), timeout.
sasaBRead-onlyIdempotent
Solvent-accessible surface area (Angstrom^2) of a selection, per frame.
srad is the solvent probe radius (1.4 A ~ water).
Inputs: structure (required), srad, selection, trajectory.
vmd_infoARead-onlyIdempotent
Return the VMD version/banner and the resolved launcher path. Use this first to confirm the server can reach a working VMD.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool has a clearly distinct purpose: contacts for atom pairs, count_atoms for counting, distance for center distance, molecule_info for summary, radius_of_gyration for RG, render_image/image renderings, rmsd/rmsf for structural alignment, run_tcl for arbitrary scripts, sasa for surface area, and vmd_info for version. No two tools have overlapping functionality.
All names use lowercase underscores. Some are single nouns (contacts, distance, rmsd, rmsf, sasa) while others are verb_noun (count_atoms, render_image, render_preset, run_tcl). This is mildly inconsistent but still readable and predictable.
With 12 tools, the set covers a wide range of common VMD analyses (distance, RMSD, RMSF, SASA, contacts, radius of gyration, rendering) without being overwhelming. The count is appropriate for the domain.
The tools cover core analysis tasks (geometry, structural alignment, surface area, rendering, counting, contacts). Missing explicit tools for angles/dihedrals or hydrogen bonds, but the run_tcl fallback allows arbitrary scripts, filling most gaps.
Maintenance
Related MCP Connectors
Direct AI video, image, music and storyboard production from any MCP client.
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
Physics-based validation of simulation results: receipts with per-check verdicts, via MCP.
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables control of VMD2 for molecular dynamics analysis through natural language, allowing users to load structures, set representations, measure distances, compute RMSD, and render images without Tcl scripting.8-
- AlicenseAqualityDmaintenanceEnables natural language control of UCSF ChimeraX for protein structure visualization, editing, and analysis through MCP clients.3941 PyPI3MIT
- AlicenseBqualityDmaintenanceMCP server for controlling UCSF ChimeraX molecular visualization software, enabling command execution, screenshots, structure analysis reports, and session management.272MIT
- AlicenseBqualityBmaintenanceHeadless PyMOL for molecular visualization, GROMACS/LAMMPS MD trajectories, and clathrate-hydrate cage analysis: H-bond networks, F3/F4 order parameters, and TRACE cage perception + occupancy.321MIT