PyMOL-MCP: Control PyMOL with Claude or OpenAI Codex

PyMOL-MCP connects PyMOL to AI clients through the Model Context Protocol (MCP), enabling Claude and OpenAI Codex to directly interact with and control PyMOL. It supports conversational structural biology, molecular visualization, and analysis through natural language.

Features

• Two-way communication: Connect Claude or Codex to PyMOL through an MCP server
• Intelligent command parsing: Natural language processing for PyMOL commands
• Molecular visualization control: Manipulate representations, colors, and views
• Structural analysis: Perform measurements, alignments, and other analyses
• No arbitrary code execution: Only allowlisted cmd.* calls are dispatched, with no exec() or eval()

Prerequisites

• PyMOL installed on your system
• Claude Desktop, Claude Code, or OpenAI Codex
• Git
• Make, if you want to use the Quick Start

Quick Start

For Claude Code, with uv, PyMOL and Make installed:

git clone https://github.com/jonathan6620/pymol-mcp
cd pymol-mcp
uv sync
claude mcp add pymol -s user -- uv --directory $(pwd) run pymol-mcp
make install

For OpenAI Codex, replace the claude mcp add command with:

codex mcp add pymol -- uv --directory "$(pwd)" run pymol-mcp

Restart PyMOL and start a new Claude Code session. On startup PyMOL prints MCP socket plugin auto-started on port 9876, or the next free port.

If make cannot find the PyMOL executable, then pass the path: make install PYMOL=/full/path/to/pymol.

For Claude Desktop, use Step 3, Option A in place of the claude mcp add line, then run make install.

Full Installation Guide

Step 1: Install the uv Package Manager

On macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or, on macOS with Homebrew:

brew install uv

On Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
set Path=C:\Users\[YourUsername]\.local\bin;%Path%

For other platforms, visit the uv installation guide.

Step 2: Clone the Repository

git clone https://github.com/jonathan6620/pymol-mcp
cd pymol-mcp
uv sync

Step 3: Configure your MCP client

Use Claude Desktop, Claude Code, or OpenAI Codex.

Option A: Claude Desktop

1. Open Claude Desktop
2. Go to Claude > Settings > Developer > Edit Config
3. This will open the claude_desktop_config.json file
4. Add the MCP server configuration:

{
  "mcpServers": {
    "pymol": {
      "command": "[Full path to uv]",
      "args": [
        "--directory",
        "[Full path to the cloned pymol-mcp repo]",
        "run",
        "pymol-mcp"
      ]
    }
  }
}

For example:

{
  "mcpServers": {
    "pymol": {
      "command": "/Users/username/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/username/pymol-mcp",
        "run",
        "pymol-mcp"
      ]
    }
  }
}

Note: Ensure that you specify the full paths for your system. Run which uv on macOS/Linux or where uv (Windows) to find the uv binary, since Claude Desktop does not inherit your shell's PATH. On Windows, use forward slashes (/) instead of backslashes.

Option B: Claude Code (CLI)

From the cloned repository directory, add the PyMOL MCP server using the claude CLI:

claude mcp add pymol -s user -- uv --directory $(pwd) run pymol-mcp

$(pwd) expands to the repo you're standing in, so run this from the pymol-mcp directory you cloned in Step 2. From anywhere else, pass the full path instead:

claude mcp add pymol -s user -- uv --directory /path/to/pymol-mcp run pymol-mcp

This saves the configuration to ~/.claude.json. You can verify it was added with:

claude mcp list

Note: After adding the MCP server, you must restart your Claude Code session for the tools to become available.

Option C: OpenAI Codex

From the cloned repository directory, register the local stdio MCP server:

codex mcp add pymol -- uv --directory "$(pwd)" run pymol-mcp

Verify the configuration with codex mcp list. Codex stores MCP configuration in ~/.codex/config.toml; the Codex CLI, IDE extension, and ChatGPT desktop app on the same Codex host share it. Restart the client after adding the server.

The equivalent manual configuration is:

[mcp_servers.pymol]
command = "uv"
args = ["--directory", "/full/path/to/pymol-mcp", "run", "pymol-mcp"]

Step 4: Install the PyMOL Socket Plugin

The MCP server communicates with PyMOL over a socket. Each PyMOL claims its own port in the range 9876-9895, so several instances can run at once. Install the socket listener plugin from the repository you cloned in Step 2:

pymol -cq scripts/install_plugin.py

Restart PyMOL afterwards, so it picks up the new plugin.

Step 5: Start the PyMOL Socket Listener

Before Claude can send commands to PyMOL, the socket listener must be active. Run this command to configure PyMOL to launch the plugin when the app opens.

make install-pymolrc

If make is not installed, create or edit ~/.pymolrc.py.

import importlib, threading, time

# PyMOL imports plugins from its startup directory under this name, so there is
# no path to configure -- it is identical on every machine and every PyMOL
# distribution. Requires the plugin to be installed (Step 4).
PLUGIN_MODULE = "pmg_tk.startup.pymol-mcp-socket-plugin"

def _auto_start_mcp_socket():
    time.sleep(3)  # let PyMOL's plugin system finish initializing
    try:
        plugin = importlib.import_module(PLUGIN_MODULE)
    except ImportError:
        print("MCP socket plugin not installed -- run: pymol -cq scripts/install_plugin.py")
        return
    try:
        # No port argument: claim the first free one, so a second PyMOL gets
        # its own listener rather than silently having none.
        if plugin.start_socket_server():
            print(f"MCP socket plugin auto-started on port {plugin.current_port}")
        else:
            print("MCP socket listener not started; every port in range is in use.")
    except Exception as e:
        print(f"MCP socket auto-start failed: {e}")

# Background thread so PyMOL startup isn't blocked
threading.Thread(target=_auto_start_mcp_socket, daemon=True).start()

Usage

Starting the Connection

With the socket listener running (Step 5):

• Claude Desktop: a hammer icon appears in the tools section when chatting; click it to access the PyMOL tools.
• Claude Code (CLI): start a new session in the terminal.

Example Commands

Here are some examples of what you can ask Claude to do:

• "Load PDB 1UBQ and display it as cartoon"
• "Color the protein by secondary structure"
• "Highlight the active site residues with sticks representation"
• "Align two structures and show their differences"
• "Calculate the distance between these two residues"
• "Save this view as a high-resolution image"

Multiple PyMOL instances

Each PyMOL claims its own port, so you can run several and drive any of them. Ask Claude to list them, then name the one you mean:

> list the PyMOL instances
  instance=9876, pid 4412: 1ubq
  instance=9877, pid 4488: 6vxx

> in 9877, colour chain A red

When more than one PyMOL instance is running, Claude must be directed to the correct one.

The PyMOL skill

make install also installs a skill from skills/pymol-mcp/, which gives Claude Code and Codex higher-level guidance on driving this MCP server. To install it on its own:

make install-skill

It goes into both ~/.claude/skills/ and Codex's ~/.agents/skills/, so it applies in any project directory. Start a new client session afterwards.

Session history

Every command is written to disk as it runs, so a session survives PyMOL closing. Two files in ~/.pymol-mcp/:

File	Contents
history.jsonl	Every command with its arguments, outcome, and any error
session-<timestamp>.pml	The successful commands only, as PyMOL syntax

Replay a session, or reuse it as a figure script:

pymol -r ~/.pymol-mcp/session-20260722-114646.pml

load, save, and png also record the absolute path they touched, since PyMOL resolves a relative path against its own working directory.

Set PYMOL_MCP_HISTORY=/some/dir to write elsewhere, or PYMOL_MCP_HISTORY=off to disable. The variable is read from the environment PyMOL was launched from.

Troubleshooting

• Connection issues: Make sure the PyMOL plugin is listening before attempting to connect from Claude

• Command errors: Check the PyMOL output window for any error messages

• MCP socket plugin not installed on PyMOL startup, run pymol -cq scripts/install_plugin.py

• Dialog says "Not listening" while the port is in use: your ~/.pymolrc.py loads the plugin by file path, giving the dialog and the listener separate copies of the module. Use the snippet in Step 5.

• ~/.pymolrc.py is ignored: PyMOL searches the working directory before $HOME and stops at the first directory holding a pymolrc* or .pymolrc* file, so launching from such a directory shadows your home config. To print the files PyMOL loads:

  pymol -cq -d "import pymol.invocation as i; print(i.get_user_config())"
  

• Plugin not appearing: Restart PyMOL and check that the plugin was correctly installed

• Claude not connecting: Verify the paths in your Claude configuration file are correct

• Garbled client display: PyMOL writes to the terminal it was launched from, which corrupts the display of a terminal client such as Claude Code. Launch PyMOL from its desktop icon or a separate terminal.

• Server diagnostics: The server logs nothing by default, because MCP clients treat a stdio server's stderr as an error stream and display every line. Set PYMOL_MCP_LOG_LEVEL=INFO (or DEBUG) in the server's env block to turn logging back on.

Security

The listener binds to localhost and has no authentication, so any local process can drive PyMOL through it.

alter and alter_state take expressions that PyMOL evaluates as Python. The plugin parses those first and allows only arithmetic over atom properties, rejecting attribute access, subscripting, lambdas and comprehensions.

Limitations & Notes

• The socket connection requires both PyMOL and Claude to be running on the same machine
• Some complex operations may need to be broken down into simpler steps
• Always save your work before using experimental features

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

src/pymol_mcp/         MCP server and models; entry point `pymol-mcp`
pymol-mcp-socket-plugin/   PyMOL plugin (the directory name is the module
                           name PyMOL imports, so it cannot change)
scripts/               install_plugin, install_pymolrc, install_skill
skills/pymol-mcp/      Claude Code skill
tests/                 pytest suite; conftest.py stubs the MCP framework

Run the test suite and linters with uv:

uv run pytest
uv run ruff check .

Or Make:

make test
make lint

Credits

Derived from vrtejus/pymol-mcp by Vishnu Rajan Tejus.

• Replaced exec() with an allowlisted command dispatcher
• Added Pydantic models, type hints, and a test suite
• Reworked setup around uv and added Claude Code CLI instructions

License

MIT. See the LICENSE file. Copyright is held jointly by the original author and subsequent contributors; the original copyright notice is retained as the license requires.