skblnw/mcp-visualization

PyMOL Protein Visualization MCP Server

A professional-grade Model Context Protocol (MCP) server for generating publication-quality protein structure visualizations using PyMOL. This unified server provides two specialized workflows for both detailed protein-residue interaction analyses and multi-component protein visualizations.

Features

• Unified MCP server with two specialized analysis workflows
• Publication-quality output with ray tracing and professional styling
• Multi-stage workflows with user interaction and verification points
• Flexible residue selection and distance measurement capabilities
• Support for multi-chain proteins and functional unit grouping
• Automated PyMOL command generation following best practices

Analysis Workflows

Detailed Analysis - 7-Stage Workflow

• Focused on detailed protein-residue interactions
• Advanced rendering optimization with ray tracing
• Comprehensive distance measurements between atom pairs
• Cα atom identification with distinct colors
• Ideal for: Active site analysis, enzyme mechanisms, binding interactions

Multi-Component Analysis - 6-Stage Workflow

• Optional functional unit grouping for protein complexes
• Support for multi-chain protein complexes (TCR-pMHC, antibody-antigen, etc.)
• Hydrogen bond analysis at interfaces
• Chain-aware residue specification
• Ideal for: Protein complexes, multi-domain proteins, comparative analysis

Installation

Prerequisites

• Python 3.7+
• PyMOL (installed separately)
• MCP-compatible client

Install Dependencies

pip install -r requirements.txt

Usage

Starting the MCP Server

python3 pymol_server.py

The server communicates via MCP protocol over stdio.

Prompt Templates

detailed_analysis

Parameters:
- pdb_id (required): PDB code (e.g., "9def", "1abc")
- key_residues (optional): Comma-separated residue list (e.g., "57,102,195")  
- distance_pairs (optional): Atom pairs for measurement (e.g., "T99:CA-H17:NE2;S142:OG-D37:OD1")
- special_requirements (optional): Custom visualization needs

multi_component_analysis

Parameters:
- pdb_id (required): PDB structure code
- protein_components (optional): Functional grouping (e.g., "TCR:A+B;pMHC:C+D+E")
- key_residues (optional): Chain-aware residues (e.g., "A:57,102,195")
- distance_pairs (optional): Distance measurements between residues
- special_requirements (optional): Custom visualization needs

Example Workflows

Detailed Analysis Workflow

1. Load protein structure from PDB
2. Select and highlight key catalytic residues
3. Apply professional color schemes and rendering
4. User verification checkpoint - save initial view
5. Focus on active site with detailed atomic representation
6. Add Cα atom markers with distinct colors
7. Measure specific atomic distances
8. Generate final publication-ready image

Multi-Component Analysis Workflow

1. Load multi-chain protein complex
2. Group chains into functional units (e.g., TCR vs pMHC)
3. Apply distinct colors to each functional unit
4. Highlight interface residues with atomic detail
5. User verification checkpoint - save overview
6. Perform hydrogen bond analysis at interface
7. Generate final complex visualization

Output Quality

All visualizations are optimized for publication with:

• Ray tracing enabled for photorealistic rendering
• Professional color schemes with high contrast
• Optimized lighting and shadow settings
• High-resolution output suitable for journals
• Consistent styling across different analysis types

Integration

This MCP server integrates with:

• Any MCP-compatible client or framework
• PyMOL-based visualization pipelines
• Automated protein analysis workflows

File Structure

mcp-visualization/
├── pymol_server.py        # Unified MCP server with both analysis workflows
├── README.md              # This file
├── requirements.txt       # Python dependencies
├── setup.py              # Package configuration
├── examples/             # Usage examples
│   └── basic_usage.py    # Basic MCP client example
└── .gitignore           # Git ignore rules

Contributing

This project focuses on defensive security applications in protein structure analysis. Contributions should maintain the professional, publication-quality standards and follow the established multi-stage workflow patterns.

License

MIT License - see LICENSE file for details.