coasir/pymol-visualization-mcp-server

PyMOL Visualization MCP Server

An automated protein structure visualization tool based on the Model Context Protocol (MCP) architecture. This server enables Claude Desktop to intelligently control PyMOL software, providing users with an interactive platform for generating high-quality, publication-ready protein structure images.

🎯 Features

• Template-Based Design: Standardized templates for single-component analysis and multi-component interactions
• Professional Rendering: Automatically applies publication-grade rendering settings
• Error Handling: Built-in comprehensive error detection and automatic recovery mechanisms
• Precise Control: Supports cross-chain residue selection and atomic-level distance measurements
• Automated Analysis:
  • Key residue visualization in single-component proteins
  • Automated protein-protein interaction (PPI) recognition
  • Atomic-level distance measurement and annotation
  • Professional-grade rendering optimization

📋 System Requirements

• Python: 3.8 or higher
• PyMOL: Latest version
• MCP: 1.0.0 or higher
• Claude Desktop: Latest version
• PyMOL-MCP Server: ChatMol/molecule-mcp (separate setup required)

🚀 Installation

1. Clone the Repository

git clone https://github.com/coasir/pymol-visualization-mcp-server.git
cd pymol-visualization-mcp-server

2. Install Dependencies

pip install -r requirements.txt

3. Setup PyMOL-MCP Server

Important: You need to set up the PyMOL-MCP bridge from ChatMol/molecule-mcp first:

1. Clone the molecule-mcp repository:

   git clone https://github.com/ChatMol/molecule-mcp.git
   

2. Follow the installation instructions in the molecule-mcp repository

4. Configure Claude Desktop

1. Open Claude Desktop
2. Navigate to Settings → Developer → Edit Config
3. Find the file named claude_desktop_config.json
4. Add both servers to your configuration:

{
  "mcpServers": {
    "pymol": {
      "command": "/PATH/TO/YOUR/MCP",
      "args": [
        "run",
        "/PATH/TO/molecule-mcp/pymol_server.py"
      ]
    },
    "pymol-visualization": {
      "command": "/PATH/TO/YOUR/PYTHON",
      "args": [
        "/PATH/TO/THIS/SERVER/804vis_en.py"
      ],
      "env": {}
    }
  }
}

5. Replace paths with your actual paths:

   • /PATH/TO/YOUR/MCP: Path to your MCP executable
   • /PATH/TO/molecule-mcp/pymol_server.py: Path to the cloned molecule-mcp server
   • /PATH/TO/YOUR/PYTHON: Path to your Python interpreter
   • /PATH/TO/THIS/SERVER/804vis_en.py: Path to this visualization server

6. Save and restart Claude Desktop

💡 Usage

Prerequisites: Ensure both MCP servers are properly configured:

• pymol (from molecule-mcp) - provides basic PyMOL control
• pymol-visualization (this project) - provides advanced visualization templates

Step 1: Launch PyMOL in Remote Mode

/PATH/TO/YOUR/PYMOL -R

Step 2: Use Templates in Claude Desktop

Single Component Analysis

Analyze and highlight specific residues in a single protein structure.

Required Parameters:

• Structure*: PDB ID or file path
• Key_residues*: Specify residues (e.g., 57,102 or A:57,B:102)

Optional Parameters:

• Distance_pairs: Define distance measurements (e.g., 57:CA-102:CA)

Multi-Component Analysis

Analyze receptor-ligand or protein-protein interaction interfaces.

Required Parameters:

• Structure*: PDB ID or file path
• Components*: Define components (e.g., receptor:A+B+C,ligand:E+D)

Optional Parameters:

• Key_residues: Specify residues (e.g., A:57,B:102)
• Distance_pairs: Define distance measurements (e.g., 57:CA-102:CA)

Workflow Overview

The following diagram illustrates the complete workflow for using the visualization templates in Claude Desktop:

📊 Examples

Single Component Analysis

• PDB ID: 9def
• Key Residues: T99, H17, S142, D37
• Result: Highlights key residues with unique colors against semi-transparent backbone

Multi-Component Analysis

• PDB ID: 1bd2
• Components: receptor:A+B+C, ligand:D+E
• Result: Interface residues highlighted with distance measurements

PD-L1 Binder Analysis

• Components: receptor:A, ligand:B
• Result: Protein-protein interaction interface analysis

📚 Documentation

⚠️ Important Notes

• Key residues should preferably not contain amino acid letters (such as T99). While the system provides error handling, there's a possibility of parsing errors.
• Remember to save the global image at pause points during the visualization workflow.
• Ensure PyMOL is running in remote mode (-R flag) before starting the visualization process.

🔧 Available Scripts

• server/804vis.py: Chinese version MCP server
• server/804vis_en.py: English version MCP server

📄 License

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

🙏 Acknowledgments

• PyMOL molecular visualization system
• Model Context Protocol (MCP) framework
• Claude Desktop integration platform
• ChatMol/molecule-mcp - PyMOL-MCP bridge implementation
• Special thanks to Kevin (GitHub: skblnw) for his invaluable support and guidance during the development of this project.

📞 Support

If you encounter any issues or have questions, please:

1. Check the
2. Open an issue on GitHub
3. Refer to the documentation in the docs/ directory

💗