pymol-mcp

Demo

Related MCP server: vmd-mcp

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

# 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?

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.

{
  "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.

• identify_cages — full TRACE cage perception: ring finding → geometric validation → constraint-propagation assembly → Euler (SEC) validation → face-count typing (5¹², 5¹²6², 5¹²6⁴, …) and an sI/sII/sH structure call.

• cage_occupancy — assign guest molecules (CO₂/CH₄) to cages and report per-type occupancy (θ_S, θ_L).

• mark_cages — drop a colored sphere at each cage centre so render_image can show the cage lattice.

• mark_cages geometry defaults — use a bold 0.18 Å cage edge radius and a 0.38 Å vertex radius by default. Pass edge_radius or vertex_radius to override them.

• order_parameter — F4 (torsional) and F3 (three-body angular). F4 ≈ 0.7–0.95 → hydrate, ≈ 0 → liquid, ≈ −0.4 → ice Ih.

• hbond_network — water H-bond graph (O–O ≤ 0.36 nm and a donor H–O···O angle < 35°) with coordination stats.

• chill_plus — classify each water as liquid, ice, or hydrate with the CHILL+ q3 bond correlation method. It returns six class counts, per-water classes, fractions, and the unique O–O network. The default cutoff is 0.35 nm. The state argument uses one-based PyMOL states and defaults to 1.

• mark_chill_plus — draw the non-liquid CHILL+ O–O network as a color-coded CGO overlay named chill_plus for render_image. It uses the same one-based state argument.

• Performance — chill_plus uses a sparse cell list for orthorhombic cells, including 90° angle roundoff within a scale-aware machine-precision tolerance. It keeps the canonical MIC distance check. It uses a bounded-temporary-memory O(n²) fallback for real tilts. Adjacency and edge outputs still scale with the edge count. Large triclinic systems need a separate benchmark.

How it works

   MCP client (Claude · Codex · Gemini …)
          │  stdio JSON-RPC
          ▼
 ┌───────────────────────────────────────────────┐
 │  pymol-mcp  (FastMCP, conda env with pymol2)    │
 │   • permanent stdout redirect (protocol-safe)   │
 │   • ONE worker thread owns + drives pymol2      │
 │   • typed @mcp.tool functions                   │
 └───────────────────────────────────────────────┘
      │ cmd.* (headless)        │ numpy / scipy (nm)
      ▼                          ▼
  PyMOL 3.x  ── ray → PNG    analysis/ (hbond, F3/F4)
                              coords via iterate_state

Requirements

Contributing

Issues and PRs welcome — see CONTRIBUTING.md.

License

MIT. The optional md extra pulls MDAnalysis (GPL-2.0-or-later), imported lazily; the core package stays MIT.