Content
# PyMOL AI Controller
## Plugins
MCP is not very user-friendly for many people, so I created another AI plugin that allows direct dialogue without the need for complex configurations like MCP.
https://github.com/Masterchiefm/pymol-ai-assistant
## MCP Tools
Control PyMOL molecular visualization software with AI through the Model Context Protocol (MCP).
This project uses the HTTP/SSE mode, supporting remote access and multi-client connections.
## Architecture
```
┌─────────────┐ HTTP/SSE ┌─────────────────┐ XML-RPC ┌─────────┐
│ AI Client │ ◄────────────► │ pymol_mcp_http │ ◄──────────► │ PyMOL │
│ (Network Connection) │ │ (HTTP Server) │ │ │
└─────────────┘ └─────────────────┘ └─────────┘
▲
│ HTTP/SSE
▼
┌─────────────┐
│ Other Clients │
└─────────────┘
```
## System Requirements
- Python 3.10+
- PyMOL 2.0+ (supports XML-RPC)
## 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 startup (listens on 127.0.0.1:3000 by default)
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 startup, the server will display:
```
🚀 PyMOL MCP HTTP server started!
Listening address: 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 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 PyMOL command line:
```python
import pymol.rpc
pymol.rpc.launch_XMLRPC()
```
### 5. Start Using
Now you can directly tell AI your requests:
```
"Fetch 1AKE structure from PDB"
"Show cartoon and color with rainbow"
"Zoom to protein center"
"Save as image"
```
## Example Conversations
### Example 1: Basic Visualization
```
You: Help me visualize the 1AKE protein structure
AI: I'll load and visualize the 1AKE protein.
[Use pymol_fetch to get 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'll analyze the binding site of 1AKE.
[Fetch structure]
[Select ligand AP5]
[Select residues within 5Å of ligand]
[Display ligand and binding site as sticks]
[Display protein surface]
Binding site analysis completed! Ligand is displayed as sticks, residues within 5Å are also displayed as sticks,
and the rest of the protein is displayed as surface, allowing clear visualization of the binding pocket.
```
### Example 3: Generate Publication-Quality Image
```
You: Generate a high-quality image of 1AKE for publication
AI: I'll generate a high-quality publication-quality image.
[Load structure]
[Set white background]
[Optimize display style]
[Perform ray tracing 2400x2400]
[Save as PNG]
High-quality image saved! Ray tracing was used with a resolution of 2400x2400 pixels,
suitable for publication.
```
## Packaging into EXE (Optional)
If you want to package the MCP server into a standalone executable file (without 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 manually package:**
```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. EXE Version MCP Configuration
When using the EXE file, MCP configuration:
```json
{
"mcpServers": {
"pymol": {
"url": "http://127.0.0.1:3000/sse"
}
}
}
```
### 4. Notes
- **File size**: About 15-20MB (including Starlette and Uvicorn)
- **Compatibility**: Packaged EXE can only run on the same operating system architecture
- **Antivirus software**: Some antivirus software may report false positives, need to add trust
- **Firewall**: HTTP server needs to open the corresponding port, please ensure the firewall allows
## Configuration File Location Description
**Qwen Code (Tongyi Lingma) configuration file location:**
- **User scope**: `~/.qwen/settings.json` (Linux/Mac), `%USERPROFILE%\.qwen\settings.json` (Windows)
- **Project scope**: `.qwen/settings.json` (in project root directory)
**Cherry Studio configuration file location:**
- **Linux/Mac**: `~/.config/cherry-studio/mcp.json`
- **Windows**: `%APPDATA%\cherry-studio\mcp.json` or `%USERPROFILE%\.cherry-studio\mcp.json`
## Startup Script
The project provides a convenient startup script:
### 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 file
- Start HTTP MCP server
- Prompt 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` | Display 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 selection chain and residue info |
| 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
`pymol_do` tool can execute arbitrary PyMOL commands, supporting complete command-line syntax.
### Common Command Quick Check
#### File Operations
```
load <file> [, <object>] [, <state>] # Load PDB/MOL/XYZ 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>] # Display 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 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> # Delete 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 properties
```
#### 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> # Superimposition
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 molecules
hetatm # Heteroatoms (ligands, water)
resi 100 around 5 # Residue 100 around 5Å
byres (sele expand 8) # Complete residues within 8Å
```
### Usage Examples
```python
# Delete water molecules and set style
pymol_do: "remove solvent; util.cbc; show cartoon"
# High-quality rendering and save
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"
# Structure alignment
pymol_do: "align structure1, structure2"
```
## API Endpoints
- **GET /sse** - SSE connection endpoint (clients connect here to get event stream)
- **POST /messages/** - Message sending endpoint (clients send JSON-RPC messages)
- **GET /health** - Health check endpoint
## PyMOL Selection Syntax Quick Check
```
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 # Residue 100 around 5Å
byres (sele expand 8) # Complete residues within 8Å
```
## Example Scenarios
### Scenario 1: Basic Protein Visualization
```
User: Help me visualize Adenylate Kinase protein
AI:
1. Use pymol_fetch to get 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 ligand as binding site
4. Display ligand and binding site as sticks
5. Display protein surface
6. Use different colors to distinguish
```
### Scenario 3: Generate Publication-Quality Image
```
User: Generate high-quality image of protein
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
### Issue: 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
```
### Issue: Unable to Connect to PyMOL
**Check:**
```bash
python test_connection.py
```
**Solution:
1. Ensure PyMOL started with `-R` parameter
2. Check PyMOL Python console for XML-RPC startup information
3. Confirm port 9123 is not occupied
4. Check firewall settings
5. Try restarting PyMOL
### Issue: Command Execution Failed
**Check:
- Ensure object name is correct
- Ensure selection syntax is correct
**Solution:
Use `pymol_do` tool to execute raw PyMOL commands 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 features
- [ ] Support more file formats
## References
- [PyMOL Wiki](https://pymolwiki.org/)
- [MCP Documentation](https://modelcontextprotocol.io/)
- [PyMOL Command Reference](https://pymolwiki.org/index.php/Category:Commands)
## License
MIT License
