PyMOL MCP connects Claude Code to PyMOL via the Model Context Protocol, letting you control molecular visualizations. Describe what you want — fetch a structure, highlight active-site residues, color by secondary structure, measure distances — and Claude translates it into PyMOL commands in real time. It works locally on Mac or remotely on an HPC cluster through a simple SSH reverse tunnel, with no plugins or GUI interaction required.

Claude picks from three MCP tools (run_command, run_python, pymol_get) to talk to PyMOL over XML-RPC.

• PyMOL
• Claude Code (npm install -g @anthropic-ai/claude-code)
• Python 3.10+

pymol -R

Since PyMOL runs on your local Mac and Claude Code runs on the remote HPC, you need an SSH reverse tunnel to bridge them.

1. Clone the repo on HPC

git clone https://github.com/nagarh/pymol-claude-code
cd pymol-claude-code

2. Install dependencies on HPC

pip install mcp

3. Choose a free port on HPC

try <PORT>  = 49123 to check it is free or not 

ss -tlnp | grep <PORT> || echo "port is FREE" 

4. Update the port in pymol_mcp_server.py

Change this line to match your chosen port:

pymol = xmlrpc.client.ServerProxy('http://localhost:<PORT>')

5. Register the MCP server with Claude Code on HPC

claude mcp add pymol python3 ./pymol_mcp_server.py

claude mcp list 

Verify this output 
pymol: python3 ./pymol_mcp_server.py - ✓ Connected

6. On your PC — start the SSH reverse tunnel

Skip this step if you are on a local Linux machine; it is only needed if you followed the above steps on an HPC system.

ssh -R <PORT>:localhost:9123 <user>@<hpc-address> 

7. Open Claude Code

claude

1. Clone the repo

git clone https://github.com/nagarh/pymol-claude-code
cd pymol-claude-code

2. Create virtual environment and install dependencies

python3 -m venv venv
source venv/bin/activate
pip install mcp

3. Register the MCP server with Claude Code

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

claude mcp list

verify this output:
pymol_mcp_server.py - ✓ Connected

4. Open Claude Code

claude

PyMOL must be running with XML-RPC before using Claude Code.

Once connected, Claude can control PyMOL directly. Example prompts:

• fetch 1hho and show the protein as cartoon
• remove water molecules and show surface
• select residues within 4 angstroms of the ligand
• color the helices salmon and the ligand yellow

By default Claude Code asks for approval every time a PyMOL tool is called. To disable this, add the following to your ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(*)",
      "mcp__pymol__*"
    ]
  }
}

OR

echo '{"permissions":{"allow":["Bash(*)","mcp__pymol__*"]}}' > ~/.claude/settings.json

This allows all PyMOL MCP tools (run_command, run_python and pymol_get) without prompting.

MCP server shows failed

• Check that PyMOL is running with XML-RPC enabled
• Verify the port in pymol_mcp_server.py matches your tunnel port
• Restart Claude Code after changing the port

Port is stuck on HPC

• Always press Ctrl+C on the SSH tunnel before closing the terminal
• Use a different port if stuck: ss -tlnp | grep <PORT> || echo "FREE"
• Stuck ports are released by HPC's sshd automatically after some time

Name: Hemant Nagar
Email: hn533621@ohio.edu