Pymol-Claude-MCP

An MCP server that lets Claude Code drive a live PyMOL session — fetch structures, build selections, adjust representations and coloring, measure distances — by talking to PyMOL's built-in XML-RPC server.

How it works

PyMOL ships with an XML-RPC server (enabled via pymol -R) that exposes its command API on localhost:9123. pymol_server.py wraps that in three MCP tools so Claude can call them like any other tool:

Claude decides which tool fits the request and supplies the PyMOL command or code itself — this server is just the transport layer.

Prerequisites

• PyMOL (with XML-RPC support — the open-source build includes it)
• Claude Code: npm install -g @anthropic-ai/claude-code
• Python 3.10+

Setup

1. Clone this repo and install dependencies

git clone https://github.com/<your-username>/Pymol-Claude-MCP
cd Pymol-Claude-MCP
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Make PyMOL start its RPC server automatically (optional but recommended)

By default you'd need to launch PyMOL from a terminal with pymol -R every time. Instead, symlink autostart/pymolrc.py to ~/.pymolrc.py — a script PyMOL runs on every launch — so RPC starts silently whether you open PyMOL from the command line, Spotlight, or the Dock:

ln -sf "$(pwd)/autostart/pymolrc.py" ~/.pymolrc.py

From now on, just open PyMOL normally. It listens for the MCP server on port 9123 (override with PYMOL_RPC_PORT).

If you'd rather not touch ~/.pymolrc.py, start it manually instead each time: pymol -R.

3. Register the server with Claude Code

claude mcp add pymol $(pwd)/venv/bin/python3 $(pwd)/pymol_server.py
claude mcp list

You should see:

pymol: .../venv/bin/python3 .../pymol_server.py - ✓ Connected

4. Launch Claude Code

claude

PyMOL must already be running (with RPC active — automatic if you did step 2, otherwise via pymol -R) before Claude Code starts, or the server will fail to connect.

Using a different port

If 9123 is taken, start PyMOL's RPC server on another port and point the MCP server at it:

pymol -cq -d "rpc_launch(port=49123)"

claude mcp add pymol $(pwd)/venv/bin/python3 $(pwd)/pymol_server.py -- --port 49123

(or set PYMOL_RPC_PORT=49123 in the environment instead of passing --port)

Remote setup (PyMOL local, Claude Code on a remote host)

If PyMOL runs on your own machine but Claude Code runs elsewhere (e.g. an HPC login node), open an SSH reverse tunnel so the remote host can reach your local PyMOL's RPC port:

ssh -R 9123:localhost:9123 <user>@<remote-host>

Then follow the same setup steps on the remote host, pointing claude mcp add at a Python environment there.

Example prompts

• "Fetch 1hho and show it as a cartoon"
• "Remove waters and switch to surface representation"
• "Select everything within 4 Å of the ligand"
• "Color helices salmon and the ligand yellow"
• "How many chains are in this structure?"

Auto-approving tool calls

By default, Claude Code confirms before each PyMOL tool call. To skip that, add to ~/.claude/settings.json:

{
  "permissions": {
    "allow": ["mcp__pymol__*"]
  }
}

Note that pymol_script executes arbitrary Python inside the PyMOL process — treat auto-approval the same way you would for any tool that runs unrestricted code locally.

Troubleshooting

zsh: command not found: pymol

• The macOS .app build of PyMOL doesn't put pymol on your PATH. Either use the full path — /Applications/PyMOL.app/Contents/bin/pymol -R — or add that directory to your PATH.

MCP server shows failed

• Confirm PyMOL is running with RPC active (automatic with autostart/pymolrc.py, or via -R)
• Confirm the port matches between PyMOL and the --port/PYMOL_RPC_PORT value
• Restart Claude Code after changing the port

Connection refused

• PyMOL must be started before Claude Code connects to the MCP server
• If using the SSH tunnel setup, confirm the tunnel is still open (Ctrl+C closes it)