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()

Related MCP server: BlenderMCP

Prerequisites

• PyMOL — see Step 0

• Claude Desktop, Claude Code, or OpenAI Codex

• Git

• Make, if you want to use the Quick Start

Quick Start

One script does the whole setup, installing uv, PyMOL, the plugin, the skill, and the MCP client registration — whichever of those is missing:

git clone https://github.com/jonathan6620/pymol-mcp
cd pymol-mcp
./shell/install-macos.sh        # or ./shell/install-linux.sh

On Windows:

powershell -ExecutionPolicy Bypass -File shell\install-windows.ps1

It is safe to re-run, and shell/README.md documents the flags — --skip-pymol if you already have PyMOL, --skip-clients to leave your MCP config alone.

Quick Start by hand

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

git clone https://github.com/jonathan6620/pymol-mcp
cd pymol-mcp
conda env create -f environment.yml     # installs PyMOL; skip if you have it
conda activate pymol-env
uv sync
claude mcp add pymol -s user -- uv --directory $(pwd) run --frozen pymol-mcp
make install

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

codex mcp add pymol -- uv --directory "$(pwd)" run --frozen 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 0: Install PyMOL

conda env create -f environment.yml
conda activate pymol-env

That installs pymol-open-source from conda-forge — no licence key, no expiry. Schrödinger's "incentive" build works too, but needs a licence file; nothing in this server's command table depends on its extras.

Any other PyMOL install works as well; make will find it, or you can pass PYMOL=/full/path/to/pymol.

PyMOL keeps its own Python, separate from this repo's .venv — the two talk over a socket, so they never need the same packages.

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 --frozen 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 --frozen 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 --frozen 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.

The MCP server also exposes launch_pymol, which opens a GUI, retains the process handle, and waits until the new socket listener is discoverable. Clients must obtain user approval before calling it because it opens a desktop window. This is the preferred launch route in managed command environments; avoid starting pymol -q & from a disposable shell, which may reap the background process as soon as the shell exits.

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 ~/.codex/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/:

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

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

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

The get_history tool reads all of this back without needing shell access to the machine PyMOL is running on, filtered by command or to failures only.

Audit provenance and replay syntax are separate. Each JSONL record has a session_id, source describing the MCP call, plus replay and replayable when the call has valid PyMOL syntax. Composite operations may record a list of replay lines. The PID in the session filename prevents concurrent PyMOL instances from writing the same script. Read-only typed tools remain in the audit log but never enter the .pml; typed state changes are rendered as real PyMOL commands rather than Python dictionary strings. Every replay script starts with reinitialize, and load paths are made absolute in the PyMOL process that resolved them.

This deterministically reproduces MCP-controlled state. Changes made directly in the GUI are outside the protocol and therefore cannot be replayed.

Export one session for replay, debugging or later workflow analysis with the typed export_session tool:

export_session(filename="/path/to/session.zip")

The ZIP contains manifest.json, session-filtered history.jsonl, replay.pml, artifacts.json, and final-state.json. The artifact inventory references input and output paths but does not copy molecular structures or renders. A live-session export includes object, selection, camera and representation evidence; a historical export records that no live-state snapshot is available. Use redact_paths=true for a shareable analysis bundle. Redaction deliberately makes its replay.pml non-executable.

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

• ~/.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())"

• 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.

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
shell/                 per-OS setup scripts that drive the above from a
                       freshly cloned repo
skills/pymol-mcp/      Claude Code skill
tests/                 pytest suite; conftest.py stubs the MCP framework
environment.yml        conda env for PyMOL; this repo's own deps are in
                       pyproject.toml, pinned by uv.lock

Run the test suite and linters with uv:

uv run pytest
uv run ruff check .

Or Make:

make test
make lint

Credits

This project is derived from vrtejus/pymol-mcp.

This repo is maintained by Jonathan Ward. New features include an allowlisted command dispatcher, typed API, test suite, multi-instance support, installation tooling, and usage skill.

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.