pymol-mcp

Purpose

pymol-mcp's core purpose is: to make headless PyMOL act as an MCP server, letting you drive molecular visualization, GROMACS/LAMMPS molecular dynamics workflows, and scientific research on clathrate-hydrate cage structures via a large language model (LLM) using natural language.

It runs the PyMOL process in-process, with no GUI, no socket plugin, and no manual configuration. Users ask questions in ordinary language, and the model then calls typed tools, with headless PyMOL performing the rendering and returning images.

Main capabilities

Embedded and headless: maintains a long-lived PyMOL instance on a dedicated worker thread, with no clicking required, and can run in CI.

Model-visible results:render_image Renders via ray tracing and returns a PNG as MCP image content. You can use ray_style="pymolwiki_color" to get PyMOLWiki's quantified color profile configuration.

Molecular dynamics-oriented: can load GROMACS's .gro + .xtc, or bridge formats such as LAMMPS/NetCDF via MDAnalysis with in-memory coordinate injection.

Clathrate hydrate toolkit: provides hydrogen-bond networks and F3/F4 order parameters, ported from a validated Rust engine, all computed in nanometers (nm), and correctly handling triclinic periodic boundary conditions (PBC).

Typed, safe tools: every parameter is schema-validated; arbitrary code passthrough is optionally enabled (requires setting PYMOL_MCP_ALLOW_CODE_EXEC=1).

Protocol hardening: PyMOL's verbose stdout is permanently redirected, ensuring it does not corrupt the JSON-RPC stream (and is proven by a subprocess test).

Usage

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

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

Most clients use the mcpServers configuration block (Claude Code / Desktop, Gemini CLI, Cline, Continue, etc.). If you don't want to hardcode paths, you can use "command": "conda", "args": ["run", "-n", "pymol-mcp", "python", "-m", "pymol_mcp"](requires conda to be in the client's PATH). For complete from-scratch installation instructions, see llms-install.md.

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

PyMOLWiki Ray style:render_image accepts a fixed ray_style configuration. When omitted, pymolwiki_outlineis used. Explicitly using ray_style="default" preserves the current PyMOL settings. The PyMOLWiki configuration sets antialiasing to 2, uses PyMOL's built-in ray tracer, and restores the previous ray settings after each render. Setting a white background is closest to the PyMOLWiki examples.

set_projection switches the camera between orthographic projection (parallel cage edges, typical publication lattice views) and perspective projection. PyMOL's default field of view is 20°, and it can be increased (e.g., to 40) to clearly show depth of field.save_file writes PNG/PDB/PSE to disk and creates missing parent directories.list_objects Includes CGO overlays such as cages and chill_plus.

Clathrate hydrate science

Ported from a validated Rust reference implementation and re-checked against ground truth. All analyses are performed in nanometers, using the correct minimum-image convention for fractional coordinates (orthorhombic and triclinic), signed atan2 dihedral angles for F4, and a periodic-image KDTree for neighbor searches.

• identify_cages: the complete TRACE cage-aware pipeline — ring finding → geometric validation → constraint-propagation assembly → Euler (SEC) validation → face-count typing (5¹², 5¹²6², 5¹²6⁴, etc.) with sI/sII/sH structure determination.
• cage_occupancy: assigns guest molecules (CO₂/CH₄) to cages and reports the occupancy for each type (θ_S, θ_L). Guests are detected only from residue names (carbon atoms) containing CO2、CH4 or METH . The repository's bundled tests/fixtures/hydrate_sI.gro contains only TIP4P water, so its occupancy is zero.
• mark_cages: draws each cage as a wireframe polyhedron (CGO object cages) — cylinders on O–O edges and spheres at oxygen vertices, colored by type (5¹² cyan, 5¹²6² purple, 5¹²6⁴ red, 5¹²6⁸ blue, 4³5⁶6³ yellow-green). After hiding the water object, then render_image or save_file。
• mark_cages geometry defaults: by default uses a bold cage edge radius of 0.18 Å and a vertex radius of 0.38 Å, which can be overridden via edge_radius or vertex_radius .cage_types draws a subset (e.g. ["5^12 6^8"]). Cages spanning the periodic box may appear as fragments; this is a rendering limitation, not a counting error.
• order_parameter: F4 (torsion) and F3 (three-body angle). F4 ≈ 0.7–0.95 → hydrate, ≈ 0 → liquid, ≈ −0.4 → ice Ih.
• hbond_network: water hydrogen-bond graph (O–O ≤ 0.36 nm and donor H–O···O angle < 35°), with coordination-number statistics.
• chill_plus: classifies each water as liquid, ice, or hydrate using the CHILL+ q3 bond-correlation method. Returns six category counts, the category of each water, the fractions, and the unique O–O network. The default cutoff is 0.35 nm.state parameter uses 1-based PyMOL states, with a default value of 1.
• mark_chill_plus: draws the non-liquid CHILL+ O–O network as a color-coded CGO overlay named chill_plus , for use by render_image . Uses the same 1-based state parameter.

Performance:chill_plus uses a sparse cell list for orthorhombic cells, including handling 90° angle rounding within a scale-aware machine-precision tolerance, and retains the canonical MIC distance check; for genuinely tilted cells it falls back to O(n²) with bounded temporary memory. Adjacency and edge output still scale with the number of edges. Large triclinic systems require separate benchmarking.

Ground-truth validation: on the structure II reference,identify_cages Exactly 128 × 5¹² and 64 × 5¹²6⁴ cages are found (textbook 2:1 sII lattice); structure I has exactly 16 × 5¹² + 48 × 5¹²6²; structure H has 48 × 5¹² + 32 × 4³5⁶6³ + 16 × 5¹²6⁸ (16 unit cells). The F4 of the first ten waters exactly reproduces the reference value 0.926698, F3 = 0.0028 (hydrate-like ≤ 0.04), and the hydrogen-bond network is a perfect tetrahedral (average coordination number 4.00) framework.

Applicable Scenarios

Suitable for computational chemistry, molecular dynamics, and clathrate hydrate researchers, to accomplish in natural language through an LLM client: molecular structure and trajectory visualization, rendering publication-quality images, loading and inspecting GROMACS/LAMMPS trajectories, identifying and labeling hydrate cages, computing F3/F4 order parameters, analyzing water hydrogen-bond networks, and classifying water molecule states with CHILL+. Also suitable for automatically generating molecular images in GUI-less environments such as CI.

Limitations

• Must run in a Python (conda) interpreter that can import pymol2 , and cannot use uvx / fastmcp install.
• Arbitrary code passthrough is disabled by default and requires explicitly setting PYMOL_MCP_ALLOW_CODE_EXEC=1.
• Guest occupancy detection depends on the residue name containing CO2、CH4 or METH; the bundled hydrate sample contains only TIP4P water, so the occupancy is zero.
• Cage rendering across periodic boxes may appear fragmented, which is a drawing limitation.
• Performance for large triclinic systems requires separate benchmarking.
• The optional md extra introduces MDAnalysis (GPL-2.0-or-later), using lazy imports; the core package remains MIT. The project as a whole is MIT licensed.

The above information all comes from the project description; feature details not provided are explicitly not yet available.