PyMOL

You can connect PyMOL to Claude AI using the Model Context Protocol (MCP) to control molecular visualization, run analyses, and execute Python in PyMOL through natural language conversations. This setup enables two-way interaction where Claude can issue PyMOL commands, adjust representations, and fetch structural insights directly from your local environment.

How to use

You will use an MCP client on Claude Desktop to communicate with the PyMOL MCP server running locally. Start by ensuring both PyMOL and Claude are running on the same machine. In PyMOL, start the MCP Socket Plugin to listen for connections. In Claude, open the PyMOL tools from the hammer icon and begin a chat to issue visualizations, measurements, or code execution commands. Claude will translate your natural language requests into PyMOL actions and execute them through the established socket channel.

How to install

Prerequisites you need before installation:

• PyMOL installed on your system
• Claude Desktop installed
• Python 3.10 or newer
• Git installed

Step 1. Install the UV Package Manager to simplify setup.

# macOS
brew install uv

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

Step 2. Clone the project repository and enter the directory.

git clone https://github.com/vrtejus/pymol-mcp
cd pymol-mcp

Step 3. Create and activate a Python virtual environment, then install dependencies.

python -m venv venv
# macOS/Linux
source venv/bin/activate
# Windows
venv\Scripts\activate

pip install mcp

Configuration and running the MCP server

Step 4. Configure Claude Desktop to connect to the local MCP server. You will add a server entry that points to your Python environment and the PyMOL MCP server script.

{
  "mcpServers": {
    "pymol": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/pymol_mcp_server.py"]
    }
  }
}

Starting the PyMOL MCP Socket Plugin and connecting from Claude

Step 5. In PyMOL, enable the MCP Socket Plugin and start listening for connections. This prepares PyMOL to receive commands from Claude.

In PyMOL: Plugin → PyMOL MCP Socket Plugin → Start Listening

Usage examples you can try with Claude

You can ask Claude to perform many common visualization and analysis tasks, such as loading a PDB, adjusting representations, highlighting active sites, aligning structures, measuring distances, or saving high-resolution images.

Example requests you can say to Claude through the PyMOL tools: load a structure and display as cartoon; color by secondary structure; highlight active site residues with sticks; align two structures and show differences; calculate distances between residues; save the current view as an image.

Troubleshooting and notes

If you encounter connection issues, verify that the PyMOL plugin is listening and that Claude can connect to the local host. If commands fail, check the PyMOL output window for error messages. If the PyMOL plugin does not appear, restart PyMOL and re-install the plugin. Ensure the Claude configuration paths point to the exact locations of your Python executable and the server script.

Important notes: the socket connection requires PyMOL and Claude to run on the same machine. Some complex tasks may need to be broken down into simpler steps, and always save your work before using experimental features.

Security and community

Keep your local environment secure and guard any scripts or credentials you use with MCP. Consider sharing feedback and troubleshooting insights with the community to improve the integration and support for structural biology workflows.

Available tools

two_way_communication

Establish a socket-based connection that enables Claude AI to communicate with PyMOL for real-time command translation and execution.

visualization_control

Manipulate molecular representations, colors, and viewpoints directly from Claude through natural language requests.

structural_analysis

Perform measurements, alignments, and other structural analyses within PyMOL via conversational commands.

code_execution

Run arbitrary Python code inside PyMOL from Claude to extend functionality and automate tasks.

nlp_command_parsing

Natural language processing to interpret user requests and translate them into valid PyMOL commands.