jessicalh/chemviz-mcp

ChemViz MCP Server (Alpha Release)

An experimental Model Context Protocol (MCP) server that provides basic integration between RDKit computational chemistry and PyMOL molecular visualization for use with AI assistants.

Status: Alpha - Early release, expect bugs and limitations

Overview

This server attempts to bridge RDKit and PyMOL through MCP, allowing AI assistants to perform molecular calculations and visualization tasks. It uses XML-RPC to communicate with PyMOL and provides a subset of commonly used features.

Basic Capabilities

RDKit Functions

• Calculate molecular properties (MW, LogP, TPSA, etc.)
• Generate 3D conformers
• Search substructures with SMARTS
• Calculate molecular fingerprints
• Identify pharmacophore features
• Find maximum common substructures
• Generate 2D structure images

PyMOL Functions

• Load PDB structures and SMILES
• Change molecular representations
• Apply colors to selections
• Create named selections
• Measure distances
• Align structures
• Save images

Combined Functions

• Convert SMILES to 3D and visualize
• Color molecules by properties
• Basic protein-ligand visualization

Prerequisites

• Python 3.8+
• PyMOL (with XML-RPC server capability)
• RDKit
• MCP SDK

Installation

1. Clone the repository:

git clone https://github.com/yourusername/chemviz-mcp
cd chemviz-mcp

2. Create virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Start PyMOL with XML-RPC server:

pymol -R

Configuration

For Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "chemviz": {
      "command": "C:/Users/jessi/chemviz-mcp/venv/Scripts/python.exe",
      "args": ["C:/Users/jessi/chemviz-mcp/chemviz_mcp_server.py"],
      "env": {
        "PYMOL_HOST": "localhost",
        "PYMOL_PORT": "9123"
      }
    }
  }
}

For Command Line Interface

# Set environment variables
export PYMOL_HOST=localhost
export PYMOL_PORT=9123

# Run the server
python chemviz_mcp_server.py

Usage Examples

Basic Molecular Analysis

"Calculate properties for aspirin"
"Show me the 3D structure of caffeine"
"Find the MCS of these three drug molecules"

Protein-Ligand Visualization

"Load PDB 1HVH and show the binding site"
"Dock this SMILES molecule to the active site"
"Color the protein by hydrophobicity"

Pharmacophore Analysis

"Show pharmacophore features for this drug"
"Find molecules with similar pharmacophores"
"Highlight H-bond donors and acceptors"

Technical Notes

• Uses XML-RPC to communicate with PyMOL (port 9123)
• Requires PyMOL to be started with -R flag
• RDKit must be installed separately (can be challenging on Windows)

Known Issues

• Alpha release - expect bugs
• RDKit installation can be difficult on Windows
• Some PyMOL commands may not work via XML-RPC
• Limited error recovery
• No automated tests yet for all features

Troubleshooting

• PyMOL must be running: pymol -R
• Check port 9123 is available
• See TROUBLESHOOTING.md for common issues

License

MIT License - See LICENSE file

Disclaimer

This is an experimental alpha release. Not suitable for production use. No guarantees of functionality or stability.