![](\"./cover.png\")
\n Drive VMD from any LLM — render GROMACS/LAMMPS trajectories and analyze clathrate-hydrate cages through the Model Context Protocol.\n
\n\n Quick Start · Features · MCP Tools · Usage · 한국어\n
\n\n ![](\"https://img.shields.io/github/stars/wjgoarxiv/vmd-hydrate-mcp?style=social\")
![](\"https://img.shields.io/badge/license-MIT-blue\"){kind=icon}
![](\"https://img.shields.io/badge/python-3.10+-green\"){kind=icon}
![](\"https://img.shields.io/badge/MCP-server-blueviolet\"){kind=icon}
![](\"https://img.shields.io/badge/VMD-2.0b1%20%2F%201.9.4+-red\"){kind=icon}
![\"vmd-hydrate-mcp](\"./docs/media/demo.gif\")
Every frame is a real headless VMD (Tachyon) render, driven entirely through the MCP server. The sII cages — 128 × 5¹² + 60 × 5¹²6⁴ — are identified by this repo, not mocked. · ▶ full-quality MP4
\n\n## Features\n\n- **Clathrate Cage Identification** -- find and classify hydrate cages (5¹², 5¹²6², 5¹²6⁴, …) from the H-bond network and label the crystal structure (sI/sII/sH). Validated on the sII benchmark (128 small cages, exact).\n- **Photorealistic, Style-by-Prompt Cage Rendering** -- cages render with ambient occlusion + shadows, **orthographic** by default, each cage type in ONE unified color (a curated palette: 5¹²=cyan, 5¹²6⁴=red, …). Just ask: *\"show only the sII large cages in magenta with emphasized width\"* and the MCP filters, recolors, and thickens them.\n- **Stateful VMD Session** -- a persistent VMD process (Tcl socket server) keeps your molecules, selections, and camera alive across tool calls -- no reloading on every command.\n- **Hydrate Order Parameters** -- F3 (tetrahedrality) and F4 (⟨cos 3φ⟩) computed in pure NumPy, validated to the reference to 6 decimals (F4 = 0.926698 on the sII benchmark).\n- **H-bond Networks** -- water–water hydrogen-bond graph with coordination stats, the substrate for cage identification.\n- **Headless Rendering** -- CPU Tachyon ray-traced PNGs with no display or GPU, returned inline as images. Works on laptops, servers, and HPC.\n- **Attended (GUI) Mode** -- run fully offscreen (default), or set `VMD_HYDRATE_MCP_DISPLAY=gui` to open a **visible VMD window** and watch Claude load, color, rotate, and render your system live.\n- **GROMACS + LAMMPS** -- one server ingests `.gro/.xtc/.trr`, LAMMPS `.data/dump`, PDB, DCD, mmCIF.\n- **Secure by Default** -- filesystem allowlist + a Tcl command allowlist (not a bypassable denylist) + a loopback, token-gated control socket. No `run_tcl` foot-gun exposed.\n- **MCP-Native** -- clean English tool names and typed outputs; works in Claude Desktop, Claude Code, and any MCP client.\n\n## Quick Start\n\n> [!IMPORTANT]\n> **Requires a local VMD install** (2.0b1 or 1.9.4+) — this server drives *your* VMD; no registry or package ships it. On macOS, VMD lives inside a `.app`, so set `VMD_BIN` if `vmd` isn't on your `PATH`. (The pure hydrate/measure tools still work without VMD.)\n\n### Install\n\nZero-install via `uvx` (recommended):\n\n```bash\nuvx vmd-hydrate-mcp # run the server\nuvx --from 'vmd-hydrate-mcp[mda]' vmd-hydrate-mcp # + MDAnalysis for measures/selection\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/wjgoarxiv/vmd-hydrate-mcp.git\ncd vmd-hydrate-mcp && uv pip install -e \".[mda]\"\n```\n\n### Register with an MCP client\n\n**Claude Code** — one command:\n\n```bash\nclaude mcp add vmd-hydrate -- uvx vmd-hydrate-mcp\n```\n\n**Claude Desktop / any client** — add to the `mcpServers` config (or commit a project `.mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"vmd-hydrate\": {\n \"command\": \"uvx\",\n \"args\": [\"vmd-hydrate-mcp\"],\n \"env\": { \"VMD_HYDRATE_MCP_ALLOW_DIR\": \"/path/to/your/data\" }\n }\n }\n}\n```\n\n> [!IMPORTANT]\n> Set `VMD_HYDRATE_MCP_ALLOW_DIR` (os-path-separated) to the directories the server may read. All file arguments are realpath-checked against this allowlist — paths outside it are refused.\n\n### Attended (GUI) mode\n\nBy default the server drives VMD **headless** (offscreen). To instead open a **real VMD window you can watch** while Claude controls it live, add `VMD_HYDRATE_MCP_DISPLAY=gui` to the server's env:\n\n```json\n{ \"mcpServers\": { \"vmd-hydrate\": {\n \"command\": \"uvx\", \"args\": [\"vmd-hydrate-mcp\"],\n \"env\": { \"VMD_HYDRATE_MCP_DISPLAY\": \"gui\", \"VMD_HYDRATE_MCP_ALLOW_DIR\": \"/path/to/data\" }\n}}}\n```\n\nThen ask things like *\"load prod.gro, show water as points and the surfactant as VDW, then slowly rotate it\"* — the window updates in real time via `load_structure` → `add_representation` → `rotate_view`. (Requires a local desktop session; the same Tcl socket drives both modes.)\n\n## MCP Tools\n\n| Tool | Purpose | Backend |\n|---|---|---|\n| `vmd_status` | VMD version + molecules loaded in the live session | VMD |\n| `load_structure` | Load a structure/trajectory (returns a `molid`) | VMD |\n| `list_molecules` | List loaded molecules | VMD |\n| `set_representation` | Style/color/material/selection for a molecule (replaces reps) | VMD |\n| `add_representation` | Layer another representation (multi-rep views) | VMD |\n| `clear_representations` | Remove all representations | VMD |\n| `rotate_view` / `zoom_view` / `reset_view` | Live camera control (visible in GUI mode) | VMD |\n| `render` | Headless PNG of the current view | VMD + Tachyon |\n| `resolve_selection` | Atom count for a selection (catches the 0-atom `.gro` trap) | MDAnalysis |\n| `measure_geometry` | Distance / angle / dihedral by atom index | MDAnalysis |\n| `radius_of_gyration` | Rg of a selection | MDAnalysis |\n| `hydrate_order_params` | **F3 + F4 water order parameters** | NumPy |\n| `hbond_network` | **Water H-bond network + coordination** | NumPy |\n| `identify_cages` | **Cage counts (5¹²/5¹²6⁴/…) + sI/sII/sH structure** | NumPy |\n| `render_cages` | **Photorealistic cage render (AO+shadows, ortho); filter / recolor / emphasize cages by prompt** | VMD + NumPy |\n\n## Usage\n\n**1. Analyze hydrate order in a trajectory frame**\n```\nCompute the F3/F4 order parameters for hydrate.gro\n```\nReturns `f4_overall`, `f3_overall`, water count, and a plain-language interpretation (crystalline / hydrate-like / liquid / ice).\n\n**2. Render a structure**\n```\nLoad hydrate.gro, show the water oxygens as VDW spheres, and render it\n```\nProduces an inline PNG rendered headlessly with CPU Tachyon.\n\n**3. Inspect the H-bond network**\n```\nBuild the water hydrogen-bond network for hydrate.gro at frame 0\n```\nReturns bond count and average coordination (≈4 for a well-formed clathrate).\n\n**4. Style hydrate cages by prompt**\n```\nLoad hydrate.gro and show only the sII large cages in magenta with emphasized width\n```\nRenders a photorealistic, orthographic image of just the 5¹²6⁴ cages in magenta with thicker edges — the MCP maps this to `render_cages(cage_types=[\"51264\"], highlight_color=\"magenta\", emphasis=True)`. Omit the filters and every cage type is drawn in its palette color (5¹²=cyan, 5¹²6⁴=red, …).\n\n## Does it really drive VMD?\n\nYes — and you can confirm it in one command. [`examples/verify.py`](./examples/verify.py) runs the same code the MCP server exposes on a bundled sII CO₂-hydrate example: it pings the real VMD binary, identifies the cages, and renders them headlessly.\n\n```bash\npython examples/verify.py\n```\n\nExpected output:\n\n```text\n[1] VMD found : /Applications/VMD2b1.app/.../vmd_MACOSXARM64\n ping : pong 2.0b1 MACOSXARM64\n[2] Identifying cages in a real sII CO2 hydrate (1088 waters)...\n cage counts : {'51264': 60, '512': 128}\n structure : sII (confidence 0.93)\n F4 order : 0.965 (highly ordered (crystalline hydrate / ice-like))\n[3] Rendering cages headlessly (blue = 5^12, red = 5^12 6^4)...\n saved : examples/output/cages.png (362495 bytes)\nOK — vmd-hydrate-mcp drove VMD and identified the cages above.\n```\n\nThe images below are **real, unretouched VMD renders** from that pipeline (not illustrations):\n\n![](\"./docs/media/hydrate_system.png\") sII crystal — cages colored by type (cyan 5¹², red 5¹²6⁴), photorealistic Tachyon | \n![](\"./docs/media/hydrate_cage.png\") a single 5¹² dodecahedron, unwrapped across PBC (ambient occlusion + shadows) | \n