PyMOL-MCP-Vis: PyMOL + Claude AI with Visual Feedback

Forked from vrtejus/pymol-mcp - Credit to the original author for the core MCP integration.

PyMOL-MCP-Vis extends the original PyMOL-MCP with screenshot capture capabilities, enabling Claude to actually see and analyze molecular structures visually. This allows for true visual feedback loops in structural biology workflows.

What's New in This Fork

Screenshot capture - take_screenshot(width, height) captures the current PyMOL view
All-views composite - take_all_views() captures 6 orthogonal views (front, back, left, right, top, bottom) in a single composite image
Visual feedback loop - Claude can now execute commands AND verify the results visually
Optimized defaults - 200x200px default size balances quality and token efficiency

https://github.com/user-attachments/assets/687f43dc-d45e-477e-ac2b-7438e175cb36

Features

Two-way communication: Connect Claude AI to PyMOL through a socket-based 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
Code execution: Run arbitrary Python code in PyMOL from Claude

Installation Guide

Prerequisites

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

Step 1: Install the UV Package Manager

On macOS:

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/ryannmperez/pymol-mcp-vis
cd pymol-mcp-vis

Step 3: Set Up the Environment

Create and activate a Python virtual environment:

python -m venv venv

On macOS/Linux:

source venv/bin/activate

On Windows:

venv\Scripts\activate

Step 4: Install Dependencies

With the virtual environment activated:

pip install mcp

Step 5: Configure Claude Desktop

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

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

For example:

{
  "mcpServers": {
    "pymol": {
      "command": "/Users/username/pymol-mcp/venv/bin/python",
      "args": ["/Users/username/pymol-mcp/pymol_mcp_server.py"]
    }
  }
}

Note: Use the actual full paths on your system. On Windows, use forward slashes (/) instead of backslashes.

Step 6: Install the PyMOL Plugin

Open PyMOL
Go to Plugin → Plugin Manager
Click on "Install New Plugin" tab
Select "Choose file..." and navigate to the cloned repository
Select the pymol-mcp-socket-plugin/__init__.py file
Click "Open" and follow the prompts to install the plugin

Usage

Starting the Connection

In PyMOL:
- Go to Plugin → PyMOL MCP Socket Plugin
- Click "Start Listening"
- The status should change to "Listening on port 9876"
In Claude Desktop:
- You should see a hammer icon in the tools section when chatting
- Click it to access the PyMOL tools

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"

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

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
Join our Bio-MCP Community to troubleshoot, provide feedback & improve Bio-MCPS! https://join.slack.com/t/bio-mcpslack/shared_invite/zt-31z4pho39-K5tb6sZ1hUvrFyoPmKihAA

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.

PyMOL-MCP-Vis: PyMOL + Claude AI with Visual Feedback

Forked from vrtejus/pymol-mcp - Credit to the original author for the core MCP integration.

What's New in This Fork

Screenshot capture - take_screenshot(width, height) captures the current PyMOL view
All-views composite - take_all_views() captures 6 orthogonal views (front, back, left, right, top, bottom) in a single composite image
Visual feedback loop - Claude can now execute commands AND verify the results visually
Optimized defaults - 200x200px default size balances quality and token efficiency

https://github.com/user-attachments/assets/687f43dc-d45e-477e-ac2b-7438e175cb36

Features

Two-way communication: Connect Claude AI to PyMOL through a socket-based 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
Code execution: Run arbitrary Python code in PyMOL from Claude

Installation Guide

Prerequisites

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

Step 1: Install the UV Package Manager

On macOS:

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/ryannmperez/pymol-mcp-vis
cd pymol-mcp-vis

Step 3: Set Up the Environment

Create and activate a Python virtual environment:

python -m venv venv

On macOS/Linux:

source venv/bin/activate

On Windows:

venv\Scripts\activate

Step 4: Install Dependencies

With the virtual environment activated:

pip install mcp

Step 5: Configure Claude Desktop

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

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

For example:

{
  "mcpServers": {
    "pymol": {
      "command": "/Users/username/pymol-mcp/venv/bin/python",
      "args": ["/Users/username/pymol-mcp/pymol_mcp_server.py"]
    }
  }
}

Note: Use the actual full paths on your system. On Windows, use forward slashes (/) instead of backslashes.

Step 6: Install the PyMOL Plugin

Open PyMOL
Go to Plugin → Plugin Manager
Click on "Install New Plugin" tab
Select "Choose file..." and navigate to the cloned repository
Select the pymol-mcp-socket-plugin/__init__.py file
Click "Open" and follow the prompts to install the plugin

Usage

Starting the Connection

In PyMOL:
- Go to Plugin → PyMOL MCP Socket Plugin
- Click "Start Listening"
- The status should change to "Listening on port 9876"
In Claude Desktop:
- You should see a hammer icon in the tools section when chatting
- Click it to access the PyMOL tools

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"

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

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
Join our Bio-MCP Community to troubleshoot, provide feedback & improve Bio-MCPS! https://join.slack.com/t/bio-mcpslack/shared_invite/zt-31z4pho39-K5tb6sZ1hUvrFyoPmKihAA

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.