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

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

Resources & prompts

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

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.

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ı