Content
# Pymol-Claude-MCP
An MCP server that lets [Claude Code](https://claude.ai/code) drive a live [PyMOL](https://pymol.org) 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:
| Tool | Purpose |
|---|---|
| `pymol_command` | Run one PyMOL command, exactly as you'd type it at the PyMOL prompt |
| `pymol_script` | Run a block of Python inside PyMOL's embedded interpreter (loops, `cmd.*` calls, etc.) |
| `pymol_query` | Call any PyMOL XML-RPC method directly and get the return value back (for read-only lookups like atom counts or chain lists) |
Claude decides which tool fits the request and supplies the PyMOL command or code itself — this server is just the transport layer.
## Prerequisites
- [PyMOL](https://pymol.org) (with XML-RPC support — the open-source build includes it)
- [Claude Code](https://claude.ai/code): `npm install -g @anthropic-ai/claude-code`
- Python 3.10+
## Setup
**1. Clone this repo and install dependencies**
```bash
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:
```bash
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**
```bash
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**
```bash
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:
```bash
pymol -cq -d "rpc_launch(port=49123)"
```
```bash
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:
```bash
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`:
```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)
MCP Store