pymol-cursor-mcp - Truong Nguyen

Control PyMOL from Cursor via the Model Context Protocol (MCP). Describe structures and styles in plain language; the assistant calls PyMOL through XML‑RPC (run_command, run_python, pymol_get).

This project packages and documents a Cursor-first workflow. The same MCP server works with Claude Code if you prefer that CLI.

Upstream inspiration: nagarh/pymol-claude-code (PyMOL + MCP for Claude Code). This repo extends that idea with portable Cursor config, checks, scripts, and install docs.

---

Architecture

<p align="center"> <img src="flow.svg" alt="PyMOL MCP Cursor workflow — animated SVG" width="920"/> </p>

Same diagram style as upstream flow.svg, updated for Cursor (cyan node). Uses SVG/CSS animation (animateMotion, keyframes). If your Markdown preview looks static, open flow.svg directly on GitHub for the full motion.

What you get

Piece	Purpose
pymol_mcp_server.py	MCP server (stdio) → PyMOL XML‑RPC
.cursor/mcp.json	Registers the pymol MCP server using ${workspaceFolder}
.cursor/rules/*.mdc	Agent hints for PyMOL tool usage
scripts/start_pymol_for_mcp.sh	Launch PyMOL with -R (macOS/Linux)
verify_stack.py	Sanity check: venv + MCP import + RPC to PyMOL
examples/restore_pocket_labels.pml	Example PyMOL script (labels / pocket)
flow.svg	Animated architecture diagram (same style as upstream repo)

---

Quick install

git clone https://github.com/truong128/pymol-cursor-mcp.git
cd pymol-cursor-mcp

python3 -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -U pip
pip install -r requirements.txt
deactivate

Install PyMOL (conda‑forge recommended), then start RPC:

conda activate pymol_mcp          # your env with pymol-open-source
pymol -R

Or: ./scripts/start_pymol_for_mcp.sh (after chmod +x).

In Cursor: Open Folder → this repo → Settings → MCP → confirm pymol connected → restart Cursor if needed.

python3 verify_stack.py

Should print: OK: MCP import + PyMOL RPC at http://localhost:9123

Full step-by-step: INSTALL.md

---

Daily use

1. Terminal: pymol -R or VS Code/Cursor task: “PyMOL: start with XML-RPC”.
2. Cursor: Chat / Agent with this folder open.
3. Prompt: e.g. “Fetch 1hvr, cartoon on protein, sticks on ligand.”

---

Summary of changes vs “Claude Code only” upstream

Topic	Here
IDE	Cursor primary; .cursor/mcp.json, rules, tasks
RPC URL	PYMOL_RPC_URL env (default http://localhost:9123)
Paths	${workspaceFolder} — clone anywhere
Windows	.cursor/mcp.json.windows.example
Verify	verify_stack.py
PyMOL start	scripts/start_pymol_for_mcp.sh + Run Task

---

Troubleshooting

• MCP disconnected: see Cursor Output → MCP Logs; recreate venv; reopen repo root as workspace.
• PyMOL errors / missing .dylib: install PyMOL from conda-forge into a dedicated env (see INSTALL.md).
• Remote/HPC: run MCP where your editor runs; tunnel RPC (PYMOL_RPC_URL, SSH -R) — details in INSTALL.md.

---

Credits

• PyMOL MCP idea and original server: pymol-claude-code — Hemant Nagar.
• Packaging and Cursor-focused docs: truong128. - Truong Nguyen

License

MIT — see LICENSE.