MCP-GMX-VMD

MCP-GMX-VMD is a service that integrates GROMACS molecular dynamics simulations with VMD (Visual Molecular Dynamics) visualization through a microservice architecture. This tool facilitates molecular dynamics simulation setup, execution, analysis, and visualization.

Features

- Molecular Dynamics Simulations: Setup and run GROMACS simulations with an easy-to-use interface
- Trajectory Analysis: Analyze simulation trajectories (RMSD, RMSF, etc.)
- 3D Visualization: Visualize molecular structures and simulation trajectories using VMD
- Custom Workflow Directories: Create and manage simulation workflows in user-specified directories
- Modular Architecture: Built on MCP (Model Context Protocol ) for flexible integration with other tools

Prerequisites

- Python 3.9+
- GROMACS (installed and accessible in PATH)
- VMD (Visual Molecular Dynamics, installed and accessible in PATH)
- (Optional) Python VMD module for enhanced visualization capabilities

Installation

1. Clone the repository:

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

2. Create and activate a virtual environment:

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

3. Install dependencies:

   pip install -r requirements.txt
   

4. Install the package (development mode):

   pip install -e .
   

Configuration

The service uses a configuration file (config.json) for VMD path, search paths, and other settings. If this file doesn't exist, create one with the following structure:

{
  "vmd": {
    "path": "/path/to/vmd/executable",
    "search_paths": ["/path/to/search"]
  },
  "gmx": {
    "path": "/path/to/gromacs/executable"
  }
}

For macOS users, the VMD path is typically:

/Applications/VMD.app/Contents/MacOS/startup.command

Starting the Server

To start the MCP-GMX-VMD server:

python mcp_server.py

The service will start and listen for requests.

Usage Examples

Creating a simulation workflow:

import requests
Create a new workflow
response = requests.get(
    "http://localhost:8000/gmx-vmd://workflow/create?name=my_simulation"
)
workflow_id = response.json()["workflow_id"]
Prepare a simulation with custom directory
custom_dir = "/path/to/custom/directory"
response = requests.get(
    f"http://localhost:8000/gmx-vmd://simulation/prepare?workflow_id={workflow_id}&pdb_file=protein.pdb&workspace_dir={custom_dir}"
)

Analyzing trajectories:

# Analyze RMSD
analysis_params = {
    "analysis_type": "rmsd",
    "trajectory_file": "md/md.xtc",
    "structure_file": "md/md.gro",
    "selection": "protein",
    "output_prefix": "rmsd_analysis"
}
response = requests.get(
    f"http://localhost:8000/gmx-vmd://analysis/trajectory?workflow_id={workflow_id}&params={json.dumps(analysis_params)}"
)

Visualizing structures:

# Load and visualize trajectory
response = requests.get(
    f"http://localhost:8000/gmx-vmd://visualization/load-trajectory?workflow_id={workflow_id}&trajectory_file=md/md.xtc&structure_file=md/md.gro"
)

LLM Integration

This service can be integrated with LLM assistants like Claude or used with Cursor IDE for a more interactive experience. The integration allows you to perform molecular simulations and analysis directly through natural language commands.

Connect to the MCP Server

1. Copy the below JSON and replace the path placeholders with your actual system paths:

{
  "mcpServers": {
    "gmx_vmd": {
      "command": "{{PATH_TO_UV}}",
      "args": [
        "--directory",
        "{PATH_TO_SRC}/mcp-gmx-vmd",
        "run",
        "mcp",
        "run",
        "mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "{PATH_TO_SRC}/mcp-gmx-vmd",
        "MCP_DEBUG": "1",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

2. Save the configuration file to the appropriate location:
- For Claude Desktop: Save as claude_desktop_config.json in:
~/Library/Application Support/Claude/claude_desktop_config.json
- For Cursor IDE: Save as mcp.json in:
~/.cursor/mcp.json

3. Restart your application (Claude Desktop or Cursor)
- For Claude Desktop, you should now see GMX-VMD as an available integration
- For Cursor, the integration will be available after restart

Using MCP-GMX-VMD with LLMs

Once configured, you can interact with the MCP-GMX-VMD service through natural language:

- "Set up a protein simulation in water environment"
- "Analyze the RMSD of my protein trajectory"
- "Visualize this protein structure showing secondary structure"
- "Calculate hydrogen bonds in my MD trajectory"

The LLM will translate your requests into appropriate API calls to the MCP-GMX-VMD service.

Advanced Configuration

Custom Workflow Directories

To create workflows in custom directories, specify the workspace_dir parameter when creating a workflow:

response = requests.get(
    f"http://localhost:8000/gmx-vmd://workflow/create?name=custom_workflow&workspace_dir=/path/to/custom/directory"
)

VMD Visualization Templates

The service provides several built-in visualization templates for common tasks. You can apply these templates using:

response = requests.get(
    f"http://localhost:8000/gmx-vmd://visualization/apply-template?workflow_id={workflow_id}&template_name=protein_cartoon"
)

Troubleshooting

VMD Display Issues

If VMD GUI closes immediately after launch, try using one of these approaches:

1. Launch VMD in a separate terminal window (service default behavior)
2. Use vmd -dispdev text for command-line operation without GUI
3. Check VMD installation and permissions

Permission Issues

If you encounter permission issues with custom directories:

# Set appropriate permissions for the directory
chmod -R 755 /path/to/your/custom/directory

License

MIT License

YouTube Overview

Acknowledgments

- VMD is developed by the Theoretical and Computational Biophysics Group at the University of Illinois at Urbana-Champaign
- GROMACS is a versatile package for molecular dynamics simulation
- MCP (Model Context Protocol ) provides the underlying communication framework