back to resources

we have pymol at home.

pymol at home:

01 the what

pylot is a pymol plugin that lets you use pymol through claude code and cursor agents.

it turns PyMOL into an MCP server so you can drive PyMOL in English from any MCP client like Claude Code or Cursor, instead of typing PyMOL commands by hand. on startup, it spins up an MCP server — built on the official MCP Python SDK — inside PyMOL’s own Python process, exposing the pymol.cmd API as tools.

there’s also a gemmi-backed metrics layer that can parse mmCIF e.g. if you want to read confidence values (pLDDT/ipTM/pTM/PAE). you can also drop in your own .py of custom PyMOL presets / analysis helpers and ask the agent to use them, and work over SSHFS-mounted cluster paths as usual. and since it runs through Claude Code you get any Claude capabilities here too — remote-control from the mobile app, etc.

02 the why

  • vibe coding
  • automating analysis or visualisation with agents
  • remote access on mobile

03 installing

the full codebase is on GitHub. read installation instructions either here or below.

fyi - this repo is an active WIP! it’s scary in there.

note: this has only been tested on macOS :/

1. clone and install

git clone https://github.com/soo-jeongkim/pymol-claude.git
cd pymol-claude
/Applications/PyMOL.app/Contents/bin/python -m pip install --user -e .

2. hook the plugin into PyMOL startup

/Applications/PyMOL.app/Contents/bin/python -m pymol_claude.cli install-hook

appends one line to ~/.pymolrc.py so PyMOL loads the plugin on launch. safe to re-run.

3. restart PyMOL

the console should print:

pylot: MCP server running on http://127.0.0.1:8766/sse

if you don’t see that line, ~/.pymolrc.py isn’t being loaded. the file must be in your home directory (echo $HOME to check), and you need a full PyMOL quit + relaunch, not a window close.

4. wire up your MCP client

both setups are global — every Cursor window or Claude Code session sees the pymol server, no need to cd into this repo.

★ cursor

/Applications/PyMOL.app/Contents/bin/python -m pymol_claude.cli install-config

writes/merges ~/.cursor/mcp.json. fully quit Cursor (Cmd+Q, not just close the window) and reopen; verify under Settings → Cursor Settings → MCP that pymol is listed.

★ claude code

claude mcp add --transport sse --scope user pymol http://localhost:8766/sse

works from any directory. claude mcp list should show pymol.

once correct plumbing is verified, you need to open PyMOL first then a new Cursor window / Claude Code session.

04 experimenting!

click here to download a few sample CIF files you can play with.

what you are downloading: 

pizza-and-pymol/                          13 MB
└── data/
    ├── af3_predicts_pizza/
    │   ├── fold_*_model_0.cif … model_4.cif
    │   └── confidence JSONs, MSAs, templates
    ├── antibodies/
    │   ├── 1IGT.cif
    │   ├── 6XEY.cif
    │   └── 6XRJ.cif
    └── multi_domain/
        ├── 1AKE.cif
        └── 7OP8.cif