pymol-mcp

Headless PyMOL as an MCP server — drive molecular visualization, GROMACS/LAMMPS trajectories, and clathrate-hydrate cage science from your LLM.

Demo · Quick Start · Highlights · Features · Tools · Cage Science · 한국어

[!NOTE] An MCP server that embeds PyMOL in-process, headless — no GUI, no socket plugin, no manual setup. It exposes 30+ typed tools, returns rendered images inline so the model can see what it draws, loads GROMACS/LAMMPS trajectories, and ships a clathrate-hydrate analysis toolkit (H-bond networks, F3/F4 order parameters) with numerically validated science.

Demo

Ask in plain language → the model calls typed tools → headless PyMOL renders it. (full-quality MP4)

Highlights

Features

• Embedded & headless — one long-lived PyMOL instance on a dedicated worker thread; nothing to click, works in CI.
• The model can see — render_image ray-traces and returns a PNG as MCP image content. Use ray_style="pymolwiki_color" for the PyMOLWiki quantized-color outline profile.
• MD-native — load GROMACS .gro+.xtc, or bridge LAMMPS/NetCDF/… through MDAnalysis with in-memory coordinate injection.
• Clathrate-hydrate toolkit — H-bond networks and F3/F4 order parameters ported from a validated Rust engine, all in nm with correct triclinic PBC.
• Typed, safe tools — every argument is schema-validated; the arbitrary-code passthrough is opt-in (PYMOL_MCP_ALLOW_CODE_EXEC=1).
• Protocol-hardened — PyMOL's chatty stdout is permanently redirected so it can never corrupt the JSON-RPC stream (with a subprocess test that proves it).

Quick Start

[!IMPORTANT] PyMOL open-source is a conda package, and the server must run in a Python that can import pymol2. Install into that interpreter — do not use uvx/fastmcp install (they build isolated envs without PyMOL).

# 1. Create the environment (or reuse one that already has pymol-open-source)
conda env create -f env.yml        # env named `pymol-mcp`
conda activate pymol-mcp

# 2. Install this package (with the optional MD bridge + dev tools)
pip install -e ".[md,dev]"

# 3. Verify
pytest -q

It's a standard MCP server over stdio, so it works with any MCP-capable client (Claude Code / Desktop, Codex CLI, Gemini CLI, Cline, Continue, …). Point the command at the absolute conda interpreter so it can import pymol2.

Most clients use an mcpServers block (Claude Code / Desktop, Gemini CLI, Cline, Continue, …):

{
  "mcpServers": {
    "pymol": {
      "command": "/absolute/path/to/conda/envs/pymol-mcp/bin/python",
      "args": ["-m", "pymol_mcp"]
    }
  }
}

[mcp_servers.pymol]
command = "/absolute/path/to/conda/envs/pymol-mcp/bin/python"
args = ["-m", "pymol_mcp"]

Prefer not to hardcode a path? Use "command": "conda", "args": ["run", "-n", "pymol-mcp", "python", "-m", "pymol_mcp"] instead (requires conda on the client's PATH). See llms-install.md for a full from-scratch setup.

To enable the opt-in scripting tools, add "env": {"PYMOL_MCP_ALLOW_CODE_EXEC": "1"} to the server entry.

Then ask your agent things like:

Load ./hydrate.gro, color water by F4 order parameter, and render it.
Load md.gro + traj.xtc, show CO2 guests as spheres, render frame 50.
What's the mean H-bond coordination of the water in this structure?
Load tests/fixtures/hydrate_sII.gro, identify and mark cages, hide the waters, set orthographic projection, and render.

Tool Catalog

PyMOLWiki Ray styles

render_image accepts a fixed ray_style profile. If you omit it, the tool uses pymolwiki_outline. Use ray_style="default" explicitly to preserve the current PyMOL settings.

The PyMOLWiki profiles set antialiasing to 2. They use the built-in PyMOL ray tracer. They restore the previous ray settings after each render. Set a white background for the closest match to the PyMOLWiki examples.

set_projection switches the camera between orthographic (parallel cage edges, typical publication lattice) and perspective. PyMOL's default field of view is 20°; raise it (e.g. 40) to make depth obvious. save_file writes a PNG/PDB/PSE to disk and creates missing parent directories. list_objects includes CGO overlays such as cages and chill_plus.

{
  "selection": "all",
  "width": 1600,
  "height": 1200,
  "ray_style": "pymolwiki_color"
}

Domain: clathrate-hydrate science

Ported from a validated Rust reference implementation and re-checked against ground truth. All analysis runs in nanometres with a correct fractional-coordinate minimum-image convention (orthorhombic and triclinic), a signed atan2 dihedral for F4, and a periodic-image KDTree for neighbour search.