Skip to main content
Glama

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

License: MIT Python 3.10+ MCP CI Code style: ruff


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_ROOT by 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_tcl escape 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 and display resize quirks that otherwise break headless runs (see How it works).

  • Zero-config discovery — finds VMD on PATH or in macOS .app bundles (override with VMD_BIN).

Tools

Category

Tool

Purpose

Introspect

vmd_info

VMD version + resolved launcher path

molecule_info

Atoms, frames, protein/water/chain/residue counts

count_atoms

Count atoms matching a VMD selection

Analyse

radius_of_gyration

Per-frame R_gyr + min/max/mean

rmsd

Per-frame RMSD vs a reference frame (optional alignment)

rmsf

Per-atom RMSF across a trajectory

sasa

Per-frame solvent-accessible surface area

distance

Center-to-center distance between two selections

contacts

Atom-index contact pairs between selections

Render

render_image

Headless Tachyon ray-trace → PNG

render_preset

Curated render presets for common figures

Escape hatch

run_tcl

Any VMD Tcl script (with marker parsing)

Resources & prompts

Type

Name / URI

Purpose

Resource

vmd://capabilities

Tool categories, allowed render options, presets, safety defaults

Resource

vmd://output

Recent files below VMD_MCP_ROOT

Resource

vmd://examples

Compact example workflows

Prompt

render_molecule

Safe render workflow using render_preset

Prompt

analyze_trajectory

RMSD/RMSF/R_gyr/SASA trajectory workflow

Prompt

debug_vmd_failure

Triage path for path, selection, rendering, and Tcl errors

Requirements

  • VMD installed and runnable (GUI build is fine; it is used in -dispdev text mode).

  • 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-mcp
pipx install git+https://github.com/Alierkn/vmd-mcp
# or
pip install git+https://github.com/Alierkn/vmd-mcp
vmd-mcp        # starts the stdio server

Connect it to your MCP client

Claude Code

claude mcp add vmd --scope user -- \
  uvx --from git+https://github.com/Alierkn/vmd-mcp vmd-mcp

Check: 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

VMD_BIN

auto (PATH, then macOS .app)

Path to the VMD launcher

VMD_MCP_ROOT

~/vmd-mcp/output

Where rendered images / scratch are written

VMD_MCP_ALLOW_ABSOLUTE_OUTPUTS

unset / 0

Set to 1 only if render_image.output should be allowed outside VMD_MCP_ROOT

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 as bpti.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 render sample.png with the atomistic_lines preset."

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 trailing quit and stdin=DEVNULL instead.

  • display resize is unreliable without a real display — so render resolution is set via the -size W H command-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.

  • 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 tools
contactsA
Read-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_atomsB
Read-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.

distanceA
Read-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_infoA
Read-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_gyrationB
Read-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_imageA
Destructive

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_presetC
Destructive

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.

rmsdA
Read-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.

rmsfA
Read-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_tclA
Destructive

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.

sasaB
Read-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_infoA
Read-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

    A3.6/5.0

    Scored across 12 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
      -
    • A
      license
      B
      quality
      D
      maintenance
      MCP server for controlling UCSF ChimeraX molecular visualization software, enabling command execution, screenshots, structure analysis reports, and session management.
      27
      2
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Headless 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.
      32
      1
      MIT