back to resources

we have pymol at home.

pymol at home:

01 the what

co-pymol is a pymol plugin that lets you use pymol through claude code, codex and cursor agents.

it turns PyMOL into an MCP server so you can drive PyMOL in English from any MCP client like Claude Code, Codex 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 and Codex you get any Claude/Codex capabilities here too — remote-control from the mobile app, etc.

02 the why

  • 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.

if you’d rather have a coding agent (Claude Code, Cursor, Codex, etc.) do the install for you, point it at AGENTS.md — it’s the same recipe written for an agent to execute.

note: this has only been tested on macOS :/

1. clone and install

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

2. set up the MCP client you use

choose exactly one. each command installs the PyMOL startup hook and configures only that client. setup is global — every Codex, Cursor or Claude Code session sees the pymol server, no need to cd into this repo. safe to re-run.

★ codex

/Applications/PyMOL.app/Contents/bin/python -m co_pymol setup codex

★ cursor

/Applications/PyMOL.app/Contents/bin/python -m co_pymol setup cursor

★ claude code

/Applications/PyMOL.app/Contents/bin/python -m co_pymol setup claude

codex and claude code need their CLI on your PATH; cursor writes ~/.cursor/mcp.json directly. these commands don’t install the clients themselves.

3. restart PyMOL and your client

the PyMOL console should print:

co-pymol: 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.

then confirm your client has the entry: codex mcp list, claude mcp list, or Cursor Settings → MCP.

4. verify the plumbing between your agent and PyMOL

ask something like “are you connected to PyMOL? what version is loaded?” — if it calls a pymol tool and reports a real answer, you’re wired up. if it can’t see any pymol tools, re-check step 2 and open a new session.

once correct plumbing is verified, you need to open PyMOL first then a new Codex / Cursor / 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