Content
# PyMOL AI Controller
## Plugin
MCP is not very user-friendly for many people, so I made another AI plugin that allows direct dialogue without the need for complex configurations like MCP.
https://github.com/Masterchiefm/pymol-ai-assistant
## MCP Tool
Control the PyMOL molecular visualization software through the MCP (Model Context Protocol) protocol.
This project uses HTTP/SSE mode, supporting remote access and multi-client connections.
## Architecture Description
```
┌─────────────┐ HTTP/SSE ┌─────────────────┐ XML-RPC ┌─────────┐
│ AI Client │ ◄────────────► │ pymol_mcp_http │ ◄──────────► │ PyMOL │
│ (Network) │ │ (HTTP Server) │ │ │
└─────────────┘ └─────────────────┘ └─────────┘
▲
│ HTTP/SSE
▼
┌─────────────┐
│ Other Clients │
└─────────────┘
```
## System Requirements
- Python 3.10+
- PyMOL 2.0+ (with XML-RPC support)
## Quick Start
### 1. Install Dependencies
```bash
pip install mcp starlette uvicorn
```
Or install all dependencies:
```bash
pip install -r requirements.txt
```
### 2. Start HTTP Server
```bash
# Basic start (default listen on 127.0.0.1:3000)
python pymol_mcp_server.py
# Specify host and port
python pymol_mcp_server.py --host 0.0.0.0 --port 3000
# Specify PyMOL connection parameters (if PyMOL is remote)
python pymol_mcp_server.py --pymol-host 192.168.1.100 --pymol-port 9123
```
Or use the startup script:
```bash
# Windows
start_pymol_server.bat
# Linux/Mac
chmod +x start_pymol_server.sh
./start_pymol_server.sh
```
After starting, the server will display:
```
🚀 PyMOL MCP HTTP server started!
Listening on: http://127.0.0.1:3000
SSE Endpoint: http://127.0.0.1:3000/sse
Health Check: http://127.0.0.1:3000/health
```
### 3. Configure HTTP Connection in MCP Client
**Qwen Code - Using the command line:**
```bash
# Add SSE server
qwen mcp add --transport sse pymol http://127.0.0.1:3000/sse
```
**Qwen Code - Configuration file (`.qwen/settings.json`):**
```json
{
"mcpServers": {
"pymol": {
"url": "http://127.0.0.1:3000/sse",
"timeout": 30000
}
}
}
```
**Cherry Studio - Configuration file:**
```json
{
"mcpServers": {
"pymol": {
"url": "http://127.0.0.1:3000/sse"
}
}
}
```
**Claude Desktop - Configuration file (`claude_desktop_config.json`):**
```json
{
"mcpServers": {
"pymol": {
"url": "http://127.0.0.1:3000/sse"
}
}
}
```
### 4. Start PyMOL
```bash
pymol -R
```
Or in the PyMOL command line:
```python
import pymol.rpc
pymol.rpc.launch_XMLRPC()
```
### 5. Start Using
Now you can directly tell the AI your needs:
```
"Fetch 1AKE structure from PDB"
"Show cartoon and color with rainbow"
"Zoom to the center of the protein"
"Save as image"
```
## Example Conversations
### Example 1: Basic Visualization
```
You: Help me see the structure of the 1AKE protein
AI: I will help you load and visualize the 1AKE protein.
[Use pymol_fetch to fetch 1AKE]
[Use pymol_show to display cartoon]
[Use pymol_color to color with rainbow]
[Use pymol_zoom to zoom]
Done! 1AKE (Adenylate Kinase) is now displayed in PyMOL, using cartoon representation and rainbow coloring scheme.
```
### Example 2: Ligand Analysis
```
You: Analyze the binding site of 1AKE
AI: I will analyze the binding site of 1AKE.
[Fetch structure]
[Select ligand AP5]
[Select residues within 5 angstroms of the ligand]
[Show ligand and binding site as sticks]
[Show protein surface]
Binding site analysis complete! The ligand is displayed as sticks, and residues within 5 angstroms are also displayed as sticks.
The rest of the protein is displayed as a surface, allowing a clear view of the binding pocket.
```
### Example 3: Generate Publication-Quality Image
```
You: Generate a high-quality 1AKE image for publication
AI: I will generate a high-quality publication-grade image.
[Load structure]
[Set white background]
[Optimize display style]
[Ray trace 2400x2400]
[Save PNG]
High-quality image saved! Ray tracing rendering was used, with a resolution of 2400x2400 pixels,
suitable for publication.
```
## Package into EXE (Optional)
If you want to package the MCP server into a standalone executable file (without a Python environment), you can use PyInstaller:
### 1. Install PyInstaller
```bash
pip install pyinstaller
```
### 2. Package
**Using the provided packaging script:**
```bash
python build_exe.py
```
**Or package manually:**
```bash
pyinstaller --onefile --console --name pymol-mcp-server pymol_mcp_server.py --hidden-import=starlette --hidden-import=uvicorn
```
After packaging, the executable file is located at `dist/pymol-mcp-server.exe`.
**Start EXE:**
```bash
pymol-mcp-server.exe --host 127.0.0.1 --port 3000
```
### 3. MCP Configuration for EXE Version
When using the EXE file, MCP configuration:
```json
{
"mcpServers": {
"pymol": {
"url": "http://127.0.0.1:3000/sse"
}
}
}
```
### 4. Precautions
- **File Size**: Approximately 15-20MB (including Starlette and Uvicorn)
- **Compatibility**: The packaged EXE can only run on the same operating system architecture
- **Antivirus Software**: Some antivirus software may report false positives, requiring you to add it to the trusted list
- **Firewall**: The HTTP server needs to open the corresponding port, please ensure the firewall allows it
## Configuration File Location Description
The configuration file location for **Qwen Code**:
- **User Scope**: `~/.qwen/settings.json` (Linux/Mac), `%USERPROFILE%\.qwen\settings.json` (Windows)
- **Project Scope**: `.qwen/settings.json` (in the project root directory)
The configuration file location for **Cherry Studio**:
- **Linux/Mac**: `~/.config/cherry-studio/mcp.json`
- **Windows**: `%APPDATA%\cherry-studio\mcp.json` or `%USERPROFILE%\.cherry-studio\mcp.json`
## Startup Script
The project provides convenient startup scripts:
### Windows
```bash
start_pymol_server.bat
```
### Linux/Mac
```bash
chmod +x start_pymol_server.sh
./start_pymol_server.sh
```
The script will automatically:
- Check Python and dependencies
- Check PyMOL MCP server files
- Start the HTTP MCP server
- Prompt you to start PyMOL and enable XML-RPC
## Available Tool List
| Category | Tool Name | Description |
|------|--------|------|
| File | `pymol_load` | Load local file |
| File | `pymol_fetch` | Fetch structure from PDB |
| File | `pymol_save` | Save structure to file |
| Display | `pymol_show` | Show molecular representation |
| Display | `pymol_hide` | Hide molecular representation |
| Color | `pymol_color` | Set color |
| Color | `pymol_bg_color` | Set background color |
| View | `pymol_zoom` | Zoom |
| View | `pymol_orient` | Orient |
| View | `pymol_rotate` | Rotate |
| View | `pymol_reset` | Reset view |
| Select | `pymol_select` | Create selection |
| Select | `pymol_delete` | Delete object |
| Info | `pymol_get_names` | Get object list |
| Info | `pymol_count_atoms` | Count atoms |
| Info | `pymol_get_pdb` | Get PDB string |
| Info | `pymol_get_selection_info` | Get selected chain and residue information |
| Render | `pymol_ray` | Ray tracing |
| Render | `pymol_draw` | OpenGL rendering |
| Render | `pymol_png` | Save PNG |
| Advanced | `pymol_do` | Execute arbitrary command |
## pymol_do Command Reference
The `pymol_do` tool can execute arbitrary PyMOL commands, supporting the complete command-line syntax.
### Common Command Cheat Sheet
#### File Operations
```
load <file> [, <object>] [, <state>] # Load PDB/MOL/XYZ etc. files
save <file> [, <selection>] # Save structure
fetch <code> [, <name>] # Fetch from PDB database
delete <name> # Delete object
create <name>, <selection> # Create new object
```
#### Display Control
```
show <rep> [, <selection>] # Show representation
hide <rep> [, <selection>] # Hide representation
as <rep> [, <selection>] # Switch representation
Representation (rep): lines, sticks, spheres, surface, mesh, cartoon, ribbon, dots
```
#### Color Control
```
color <color> [, <selection>] # Set color
bg_color <color> # Set background color
util.cbc # Color by chain
util.chainbow # Chain rainbow color
util.rainbow # Rainbow color
util.ss # Secondary structure coloring
```
#### Preset Styles
```
preset.simple <selection> # Simple style
preset.ball_and_stick <selection> # Ball and stick model
preset.ligands <selection> # Ligand style
preset.pretty <selection> # Pretty style
preset.publication <selection> # Publication-grade style
preset.technical <selection> # Technical style
preset.b_factor_putty <selection> # B-factor putty
```
#### View Control
```
zoom <selection> [, <buffer>] # Zoom to selection
orient <selection> # Orient to selection
center <selection> # Center align
reset # Reset view
turn <axis>, <angle> # Rotate view (axis: x, y, z)
move <axis>, <distance> # Move view
rock # Auto rock
```
#### Advanced Features
```
ray [<width>, <height>] # Ray tracing rendering
draw [<width>, <height>] # OpenGL rendering
png <file> [, <w>, <h>, <dpi>] # Save image
scene <name>, store # Save scene
scene <name>, recall # Recall scene
mplay # Play movie
mstop # Stop movie
```
#### Molecular Operations
```
remove <selection> # Remove atoms
extract <name>, <selection> # Extract atoms
h_add <selection> # Add hydrogen atoms
h_remove <selection> # Remove hydrogen atoms
remove solvent # Remove water molecules
remove hetero # Remove heteroatoms
alter <selection>, <expr> # Modify attributes
```
#### Analysis Commands
```
distance <name>, <s1>, <s2> # Measure distance
angle <name>, <s1>, <s2>, <s3> # Measure angle
rms <sel1>, <sel2> # Calculate RMSD
align <mobile>, <target> # Structure alignment
super <mobile>, <target> # Advanced alignment
centerofmass <selection> # Calculate center of mass
get_area <selection> # Calculate surface area
```
#### Selection Syntax Examples
```
all # All atoms
chain A # Chain A
resi 1-100 # Residues 1-100
resn ALA # Alanine
name CA # Alpha carbon
elem C # Carbon atom
organic # Organic ligand
hetatm # Heteroatom
sele # Current selection
(chain A and resi 50-100) # Combined conditions
(all within 5 of resi 100) # Distance selection
```
### Usage Examples
```python
# Remove water molecules and set style
pymol_do: "remove solvent; util.cbc; show cartoon"
# High-definition rendering and saving
pymol_do: "bg_color white; preset.publication (all); ray 2400, 2400; png output.png"
# Analyze ligand binding site
pymol_do: "select ligand, organic; select site, ligand expand 5; show sticks, ligand|site"
# Align structures
pymol_do: "align structure1, structure2"
```
## API Endpoints
- **GET /sse** - SSE connection endpoint (clients connect here to get the event stream)
- **POST /messages/** - Message sending endpoint (clients send JSON-RPC messages)
- **GET /health** - Health check endpoint
## PyMOL Selection Syntax Cheat Sheet
```
all # All atoms
name CA # All alpha carbons
resi 1-100 # Residues 1-100
chain A # Chain A
resn ALA # Alanine
hetatm # Heteroatoms (ligands, water)
organic # Organic molecules
resi 100 around 5 # 5Å around residue 100
byres (sele expand 8) # Select complete residues within 8Å
```
## Example Scenarios
### Scenario 1: Basic Protein Visualization
```
User: Help me visualize Adenylate Kinase protein
AI:
1. Use pymol_fetch to fetch 1AKE structure
2. Use pymol_show to display cartoon
3. Use pymol_color to color with rainbow
4. Use pymol_bg_color to set white background
5. Use pymol_zoom to zoom
```
### Scenario 2: Ligand Binding Site Analysis
```
User: Analyze the binding site of 1AKE
AI:
1. Fetch 1AKE structure
2. Select ligand (resn AP5)
3. Select residues within 5Å of the ligand as the binding site
4. Display ligand and binding site as sticks
5. Display protein surface
6. Use different colors to distinguish
```
### Scenario 3: Generate Publication-Grade Image
```
User: Generate a high-quality protein image
AI:
1. Load structure
2. Set white background
3. Optimize display (cartoon + sticks)
4. Use pymol_ray for ray tracing
5. Use pymol_png to save high-resolution image
```
## Troubleshooting
### Problem: MCP Server Not Displayed
**Check:**
```bash
# Qwen Code
qwen mcp list
```
**Solution:**
```bash
# Re-add
qwen mcp remove pymol
qwen mcp add --transport sse pymol http://127.0.0.1:3000/sse
```
### Problem: Unable to Connect to PyMOL
**Check:**
```bash
python test_connection.py
```
**Solution:**
1. Ensure PyMOL is started with the `-R` parameter
2. Check if the PyMOL Python console has XML-RPC startup information
3. Confirm that port 9123 is not occupied
4. Check firewall settings
5. Try restarting PyMOL
### Problem: Command Execution Failed
**Check:**
- Whether the object name is correct
- Whether the selection syntax is correct
**Solution:**
Use the `pymol_do` tool to execute the original PyMOL command for debugging.
## Development Plan
- [ ] Add more advanced visualization features (volume, density map, etc.)
- [ ] Support animation and movie generation
- [ ] Integrate AI structure prediction (AlphaFold, etc.)
- [ ] Add batch processing functionality
- [ ] Support more file formats
## Reference Resources
- [PyMOL Wiki](https://pymolwiki.org/)
- [MCP Documentation](https://modelcontextprotocol.io/)
- [PyMOL Command Reference](https://pymolwiki.org/index.php/Category:Commands)
## License
MIT License
