# PyMOL-MCP-Vis: PyMOL + Claude AI with Visual Feedback
> **Forked from [vrtejus/pymol-mcp](https://github.com/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:**
```bash
brew install uv
```
**On Windows:**
```bash
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](https://docs.astral.sh/uv/getting-started/installation/).
### Step 2: Clone the Repository
```bash
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:
```bash
python -m venv venv
```
**On macOS/Linux:**
```bash
source venv/bin/activate
```
**On Windows:**
```bash
venv\Scripts\activate
```
### Step 4: Install Dependencies
With the virtual environment activated:
```bash
pip install mcp
```
### Step 5: Configure 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:
```json
{
"mcpServers": {
"pymol": {
"command": "[Full path to your venv python]",
"args": ["[Full path to pymol_mcp_server.py]"]
}
}
}
```
For example:
```json
{
"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
1. Open PyMOL
2. Go to Plugin → Plugin Manager
3. Click on "Install New Plugin" tab
4. Select "Choose file..." and navigate to the cloned repository
5. Select the `pymol-mcp-socket-plugin/__init__.py` file
6. Click "Open" and follow the prompts to install the plugin
## Usage
### Starting the Connection
1. In PyMOL:
- Go to Plugin → PyMOL MCP Socket Plugin
- Click "Start Listening"
- The status should change to "Listening on port 9876"
2. 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.
