MCPymol — talk to PyMOL

MCPymol is a Model Context Protocol server that lets you drive PyMOL with natural language. Load structures, set up analytical views, measure things, and explore proteins by talking to Claude or Gemini. The image above was made by typing "show me a nucleosome" into Claude Code. That was the whole prompt.

PyMOL is great, but its syntax is famously obscure — and despite the name, it isn't quite Python. MCPymol is for people who'd rather just look at structures.

What you get

• A vocabulary the LLM understands. Tools like fetch_structure, ligand_view, interface_view, mutation_view, conservation_view do high-level setup in one call: pick the biological assembly, hide solvent, color sensibly, label the right residues, draw the right H-bonds.

• ~60 PyMOL primitives exposed as individual tools (show, hide, color, select, distance, align, spectrum, …) so the model can compose finer motions when the high-level tools don't quite fit.

• Scene introspection. list_objects, list_chains, list_ligands let the model check what's actually loaded before guessing.

• Smart structure prep. Fetching a PDB code grabs the biological assembly when one exists, then runs a BFS heuristic over chain–chain contacts (default radius 5 Å) so sprawling functional multimers like the CRP pentamer or ferritin cage stay whole while crystallographic copies get dropped. Waters and crystallization additives are hidden automatically.

• Two-process bridge. PyMOL's GUI has its own Python; MCPymol works by running a tiny TCP listener inside PyMOL plus a separate FastMCP server outside it.

Related MCP server: PubMed MCP Server

How it talks

┌──────────────┐   MCP / stdio    ┌────────────────┐   JSON over    ┌──────────────┐
│ Claude /     │ ───────────────▶ │ mcpymol server │ ◀── TCP :9876 ─▶ │ PyMOL GUI    │
│ Gemini CLI   │                  │  (FastMCP)     │                │  (plugin.py) │
└──────────────┘                  └────────────────┘                └──────────────┘

The plugin half runs inside PyMOL and dispatches to pymol.cmd. The bridge half is what the MCP client launches.

Try it

"Fetch ubiquitin (1ubq) and show it as a cartoon." "Color the alpha helices red and the beta sheets blue." "What ligands are in 1HSG?" "Show the binding pocket around MK1 in 1HSG." "Highlight mutations E6V, K16E, and V67F in hemoglobin (4HHB)." "Run a Poisson-Boltzmann electrostatics calculation on 1LYZ."

Tip: if the model isn't sure what's loaded, ask it to list the objects — it'll call list_objects and ground itself before guessing names.

Installation

There are two halves to wire up: the native plugin (runs inside PyMOL) and the MCP bridge (runs outside, and is what your AI assistant launches).

1. Start the native plugin

Open PyMOL, then in the PyMOL command line:

run /path/to/MCPymol/src/mcpymol/plugin.py

You should see MCPymol Native Plugin listening on 127.0.0.1:9876.

To auto-load it on every PyMOL launch, add this to ~/.pymolrc.py:

from pymol import cmd
cmd.do("run /absolute/path/to/MCPymol/src/mcpymol/plugin.py")

Changing the port. Set MCPYMOL_PORT before launching both PyMOL and the bridge:

MCPYMOL_PORT=9867 open -a PyMOL       # macOS
MCPYMOL_PORT=9867 uv run mcpymol      # bridge

2. Register the bridge with your AI assistant

Pick one. All paths are to the cloned repo.

git clone https://github.com/chemrich/MCPymol.git
cd MCPymol

Claude Code CLI (macOS, uv)

uv sync
claude mcp add mcpymol -- uv --directory /absolute/path/to/MCPymol run mcpymol

Start a new Claude Code session.

Claude Desktop (macOS, uv)

uv sync

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mcpymol": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/MCPymol", "run", "mcpymol"]
    }
  }
}

Restart Claude Desktop.

Gemini CLI (macOS, uv)

uv sync
gemini mcp add mcpymol uv --directory /absolute/path/to/MCPymol run mcpymol
gemini mcp refresh

Restricted environments — no uv

If uv is blocked by your org's security policy, use a standard venv. On Linux you may need sudo apt-get install python3-venv pymol first.

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .

# Point the assistant directly at the venv binary
claude mcp add mcpymol /absolute/path/to/MCPymol/.venv/bin/mcpymol
# or
gemini mcp add mcpymol /absolute/path/to/MCPymol/.venv/bin/mcpymol

If your network blocks PyPI, you may also need to tweak the repository URLs inside uv.lock to match your internal mirror.

Troubleshooting

Tests

PYTHONPATH=src uv run pytest tests/

The suite mocks the socket layer and PyMOL's cmd module, so it runs without a PyMOL install. 130+ tests cover the socket payloads, the bridge framing, the conservation pipeline (A3M parsing, Shannon entropy, MMseqs2 mocking, MSA→B-factor mapping), and every view.

The view library

These are the high-level visualization tools. Each does its own setup — coloring, transparency, H-bonds, labels — in one prompt.

ligand_view — binding site

Pocket residues (within 5 Å of the ligand) as element-colored sticks with CA labels, ligand as yellow sticks, H-bonds as yellow dashes, protein as a translucent cartoon.

Show me the ATP binding site in 1ATP

interface_view — protein–protein interface

Chain A marine, chain B salmon. Interface residues (within 4 Å of the partner) as solid surface patches with sidechain sticks and CA labels. Cross-chain H-bonds as yellow dashes.

Show the interface between chain A and chain D in 1BRS

putty_view — B-factor flexibility

Tube radius and color scale with B-factor: blue/thin = rigid, red/thick = flexible. A 70%-transparent surface adds shape context.

Show the B-factor flexibility of 1UBQ as a putty view

bfactor_view — B-factor flexibility, plain cartoon

The same color story as putty_view (blue → red on B-factor) but on a plain cartoon. Cheaper, cleaner in figures where you don't want the putty distortion.

Color 1UBQ by B-factor

hydrophobic_surface_view — surface chemistry

Surface colored by amino-acid chemistry: orange = hydrophobic, white = polar, sky blue = positive, salmon = negative. Useful for spotting hydrophobic patches, membrane belts, and charge complementarity.

Show the hydrophobic surface of 1TCA

electrostatic_view — approximate electrostatics

Red→white→blue surface coloring driven by per-residue pKa-weighted partial charges. Two modes: atomic (charges on the actual charge-center atoms — localized, natural falloff) and residue (uniform across charged residues — saturated patches).

Show the electrostatic surface of 1LYZ

poisson_boltzmann_view — true PB electrostatics

Full Poisson-Boltzmann potential via APBS and PDB2PQR, mapped onto the surface at ±20 kT/e. Physically correct, accounts for solvent screening and ionic strength.

Prerequisites (must be on PATH):

brew install brewsci/bio/apbs
pip install pdb2pqr

Run a Poisson-Boltzmann electrostatics calculation on 1LYZ

conservation_view — evolutionary conservation

Pipeline: extract the chain's sequence → submit to MMseqs2 (ColabFold public API by default; override with MCPYMOL_MMSEQS_URL) → parse the A3M alignment → compute per-position Shannon entropy → map onto B-factor and color via cyan_white_magenta spectrum.

Magenta = conserved, white = moderate, cyan = variable. First call takes 30 s – few minutes depending on sequence length; results are cached in memory by sequence, so re-running on the same protein (or changing only the color scale) is instant.

Color 1ubq by conservation

crosslink_view — disulfides & metal coordination

CYS sidechains and disulfide bonds in yellow, metal coordination bonds in orange, the rest of the protein as a thin grey cartoon.

Show the disulfide bonds in 1CEL

pocket_view — binding pocket surface

The pocket cavity (residues within 5 Å of the ligand) as a semi-transparent surface colored by chemistry. Sticks for the pocket sidechains, yellow sticks for the ligand, cyan dashes for H-bonds.

Show the binding pocket around MK1 in 1HSG

pharmacophore_view — ligand pharmacophore features

The ligand colored by pharmacophore type: violet = aromatic ring carbon, yellow = aliphatic carbon, sky blue = N (donor/acceptor), salmon = O (acceptor), gold = S, pale green = halogen. Interacting residue sticks with CA labels, cyan dashes for H-bonds.

Show the pharmacophore features of MK1 in 1HSG

mutation_view — mutation hotspots

Grey cartoon, mutated sidechains as magenta sticks with white CA labels, neighboring residues (within 4 Å) as thin element-colored sticks for packing context. Standard A123G notation; optional chain prefix A:A123G.

Highlight mutations E6V, K16E, and V67F in hemoglobin (4HHB)

textbook_view — cel-shaded illustration

White cartoon + surface with heavy ray-trace contours. The cel-shaded look kicks in after you run ray (or ask the model to render).

Make 4HHB look like a textbook illustration

cinematic_view — fog and shadows

Depth-cueing + fog + soft shadows on a black background. Best on big assemblies — ribosomes, capsids, nucleosomes — where you want a sense of scale. Run ray for the full effect.

Give me a cinematic view of the ribosome

pointillist_view — starfield surface

Replaces the surface with a dense dot cloud; ligands become bright yellow stars. More art than analysis.

🖨️ 3D Printing Export

The print_export tool turns a structure into watertight STL files ready for multi-colour 3D printing. PyMOL's open-source build can't write STL and its OBJ exporter dumps the whole visible scene as non-manifold surface soup — print_export works around all of that: it isolates each colour group, exports it, and rebuilds a single watertight, manifold solid per group. Every group stays in the same coordinate frame, so a slicer can load them as aligned multi-material parts.

This tool needs the optional print extra (trimesh, pymeshlab, scipy, scikit-image, networkx):

uv sync --extra print          # from a MCPymol checkout
uv pip install 'mcpymol[print]' # standalone

Export T7 RNA polymerase (1MSW) for 3D printing with the protein and the
nucleic acid as separate colours

This produces one STL per group (e.g. 1MSW_protein.stl, 1MSW_nucleic.stl). method="auto" (default) picks the cheapest path that works: compact structures (e.g. a GFP barrel) often export already-watertight, so it does a light cleanup — keeping the largest body and dropping tiny internal cavity shells — rather than Poisson, which can degrade an already-closed surface. Otherwise it falls back to Poisson, then voxel. method="poisson" forces detail-preserving reconstruction (best for bulky chains); method="voxel" is robust for thin nucleic acids and slightly thickens fragile features for printability. In your slicer, load the first STL, then add the others as parts (don't re-centre) and assign a filament per part.

print_ribbon_view — print-ready chunky ribbons

A preset that solves the classic problem of printing cartoons: PyMOL builds each β-strand and loop as a separate mesh segment, so the strand→loop junctions have no connecting geometry and slice into fragile, disconnected pieces. print_ribbon_view configures chunky β-strand arrows and a fat helix, hides the loop cartoon, and adds a continuous backbone spine (<obj>_spine, a cartoon tube that ignores secondary structure and runs unbroken through the whole chain). Exported together the voxel step fuses them into one watertight solid with no junction discontinuity — and the spine doubles as internal rebar for print rigidity. Tune spine_radius for more or less reinforcement.

print_ribbon_view(obj_name="1ema")
print_export(obj_name="1ema", groups="1ema=(1ema or 1ema_spine)",
             method="voxel", voxel_pitch=0.2)

The name

My best friend in high school once shared an apartment with MC Chris, who voiced MC Pee Pants in Aqua Teen Hunger Force. I'm not saying that was the inspiration for the name of this project, but I'm not denying it either.

Provenance

Built on macOS using the open-source PyMOL available via Homebrew. Started with Antigravity, then Gemini Pro 3.1 until I ran out of tokens, then Claude Code (Sonnet 4.6 thinking). Tested with Claude Code and Gemini CLI. Conservation analysis uses the ColabFold public MMseqs2 API (please don't hammer it).

License

MIT.