pymol-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PYMOL_MCP_ALLOW_CODE_EXEC | No | Set to '1' to enable opt-in scripting tools (arbitrary code execution passthrough). | 0 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| extensions | {
"io.modelcontextprotocol/ui": {}
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| load_structureA | Load a molecular structure or single-frame coordinate file into PyMOL. Returns the created object name and its atom/state counts. |
| fetch_pdbA | Fetch a structure from the RCSB PDB (requires network) and load it. |
| list_objectsA | List all loaded object names in the current PyMOL session. |
| get_object_infoA | Return atom count, state count, and chains for a loaded object. |
| reset_sessionA | Reinitialize PyMOL, clearing all objects, selections, and settings. |
| render_imageA | Ray-trace the current scene to a PNG and return it inline. |
| run_pmlA | [opt-in] Execute raw PyMOL command-language statements. Requires PYMOL_MCP_ALLOW_CODE_EXEC=1. |
| run_pythonA | [opt-in] Execute a Python snippet with PyMOL |
| selectA | Create a named selection and return how many atoms it matched. |
| get_selection_infoA | Summarize a selection: atom count, chains, and residue names present. |
| showA | Show (or exclusively set with |
| hideC | Hide a representation for a selection. |
| colorB | Color a selection. |
| spectrumA | Color a selection along a spectrum of a per-atom expression (e.g. B-factor). |
| set_backgroundA | Set the render background color. |
| orientB | Orient the camera along the principal axes of a selection. |
| zoomB | Zoom the camera onto a selection. |
| turnB | Rotate the camera about an axis. |
| measure_distanceA | Measure the distance (Angstroms) between two single-atom selections. |
| measure_angleA | Measure the angle (degrees) defined by three single-atom selections. |
| measure_dihedralA | Measure the dihedral (degrees) defined by four single-atom selections. |
| alignA | Sequence-align and superpose |
| save_fileB | Save a selection/session to a file (format from extension). |
| load_trajectoryA | Load a GROMACS/DCD trajectory: load the structure, then append frames as states. Requires matching atom count/order (trjconv strip/reorder is the common pitfall). |
| load_trajectory_mdaA | Load any MDAnalysis-readable trajectory (LAMMPS dump, AMBER NetCDF, ...) by injecting
coordinates into PyMOL states. Requires the optional |
| order_parameterA | Compute the F3 or F4 water order parameter for a clathrate-hydrate system. F4 ~ 0.7-0.95 = hydrate, ~0 = liquid, ~ -0.4 = ice Ih. F3 <= 0.04 = hydrate-like. |
| hbond_networkA | Build the water hydrogen-bond network and report coordination statistics. A well-formed clathrate framework has ~4 H-bonds per water (tetrahedral). |
| chill_plusA | Classify water molecules as liquid, ice, or hydrate with CHILL+. The result contains the six class counts, per-water classes, fractions, and the unique O-O cutoff network in water input order. |
| identify_cagesA | Identify clathrate cages (TRACE): ring perception -> cage assembly -> face-count typing. Returns per-type cage counts (5^12, 5^12 6^2, 5^12 6^4, ...) and the overall structure (sI / sII / sH). Validated: sII -> 128x 5^12 + 64x 5^12 6^4; sI -> 16x 5^12 + 48x 5^12 6^2. |
| cage_occupancyB | Compute clathrate cage occupancy: assign guest molecules to detected cages (one per cage). |
| mark_cagesA | Draw each detected cage as a wireframe polyhedron — cylinders along the O-O ring edges
plus spheres at the water-oxygen vertices, colored by cage type (5^12=cyan, 5^12 6^2=violet,
5^12 6^4=red, ...). Builds a single CGO object named |
| mark_chill_plusA | Draw the classified CHILL+ O-O network as a colored CGO object named |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 32 tools
Most tools are clearly distinct (camera, selection, representation, measurement, loading). A few pairs like load_trajectory/load_trajectory_mda and hbond_network/chill_plus show some overlap, but their descriptions provide enough clarification.
Tool names predominantly follow a verb_noun pattern (reset_session, render_image, measure_distance). Deviations exist among analysis tools (order_parameter, hbond_network, chill_plus) which use noun-style names, but the overall convention remains consistent and readable.
With 32 tools, the server is overstuffed. Several tools could be merged (e.g., measure_distance/angle/dihedral, load_trajectory variants, run_pml/run_python), and the specialized clathrate tools add bulk beyond a general-purpose PyMOL interface.
Core workflows like loading, selecting, visualizing, measuring, and rendering are covered, but basic operations such as deleting objects, listing selections, or editing structures are missing. The specialized clathrate analysis is thorough, but general PyMOL coverage has notable gaps.