wjgoarxiv/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
| | |
|---|---|
| **Runtime** | Embedded, **headless** pymol2 — no GUI, no plugin, no socket |
| **Tools** | **30+ typed tools** with real, structured return values |
| **Vision** | ray-traced PNG **returned inline** so the model sees what it draws |
| **MD trajectories** | GROMACS .xtc/.trr + LAMMPS dump (MDAnalysis bridge) |
| **Domain science** | cage perception (TRACE), occupancy, H-bonds, F3/F4 — **validated** |
| **Robustness** | worker-thread session, **stdout-safe** transport, pytest suite |
| **Safety** | arbitrary-code passthrough **off by default** |
| **Directory** | Glama (wjgoarxiv/pymol-mcp, release v0.1.0) and awesome-mcp-servers Biology (PR #9110, merged) |
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).
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, …):
Codex CLI — ~/.codex/config.toml
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:
Tool Catalog
| Group | Tools |
|-------|-------|
| **Session / IO** | load_structure · fetch_pdb · list_objects · get_object_info · reset_session |
| **Selection** | select · get_selection_info |
| **Representation** | show · hide · color · spectrum · set_background |