What is Gmx Vmd Mcp

gmx-vmd-mcp is a microservice that integrates GROMACS molecular dynamics simulations with VMD (Visual Molecular Dynamics) for simulation setup, execution, analysis, and visualization.

Use cases

Use cases include analyzing protein folding, studying molecular interactions, and visualizing simulation results for educational purposes.

How to use

To use gmx-vmd-mcp, clone the repository, set up a virtual environment, install dependencies, configure the service with the required paths, and start the server.

Key features

Key features include molecular dynamics simulations setup, trajectory analysis (RMSD, RMSF), 3D visualization of molecular structures, custom workflow management, and a modular architecture for integration with other tools.

Where to use

gmx-vmd-mcp is primarily used in computational chemistry, biophysics, and molecular biology for simulating and visualizing molecular dynamics.

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