gmx-vmd-mcp

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.

• 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 (Microservice Communication Protocol) for flexible integration with other tools

• 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

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 .

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

To start the MCP-GMX-VMD server:

python mcp_server.py

The service will start and listen for requests.

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}"
)

# 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)}"
)

# 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"
)

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.

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

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.

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"
)

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"
)

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

If you encounter permission issues with custom directories:

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

MIT License

• 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