openmm-mcp-server

OpenMM MCP Server

English | 中文

---

🧬 OpenMM & Abacus MCP Server

A comprehensive Model Context Protocol (MCP) server for molecular dynamics simulations using OpenMM and DFT calculations with Abacus. This server provides a natural language interface for complex molecular simulations through LLM integration.

✨ Features

• Complete OpenMM Integration: Support for all OpenMM features including advanced integrators, barostats, and constraints
• DFT Calculations: Abacus DFT engine integration for quantum mechanical calculations
• Pre-configured Templates: Ready-to-use setups for protein simulations, membrane systems, and more
• Advanced Sampling: Metadynamics, free energy calculations, and enhanced sampling methods
• GPU Acceleration: CUDA and OpenCL platform support for high-performance computing
• Task Management: Asynchronous task execution with persistence and monitoring
• Natural Language Interface: Interact with complex simulations using simple English commands

🚀 Quick Start

Installation

# Clone the repository
git clone <repository_url>
cd openmm-mcp-server

# Install dependencies
pip install -r requirements.txt

# Optional: Install OpenMM for actual simulations
conda install -c conda-forge openmm

# Test installation
python test_mcp_server.py

Roo Code Integration

Add to your Code/Cline/Claude MCP settings:

{
  "mcpServers": {
    "openmm-server": {
      "command": "python",
      "args": ["run_openmm_server.py"],
      "cwd": "path-to\\openmm-mcp-server",
      "alwaysAllow": [
        "create_md_simulation",
        "create_advanced_md_simulation",
        "setup_protein_simulation",
        "setup_membrane_simulation",
        "create_dft_calculation",
        "control_simulation",
        "get_task_status",
        "list_all_tasks",
        "analyze_results"
      ]
    }
  }
}

Important: Replace the path with your actual project path!

🛠️ Available Tools

Basic Tools

• create_md_simulation - Create simple MD simulations
• create_dft_calculation - Create DFT calculations
• control_simulation - Control simulation execution (start/stop/pause)
• get_task_status - Check task status
• list_all_tasks - List all tasks
• analyze_results - Analyze simulation results

Advanced Tools

• create_advanced_md_simulation - Full OpenMM feature support (50+ parameters)
• setup_protein_simulation - Pre-configured protein simulation templates
• setup_membrane_simulation - Membrane protein simulation setup

💬 Usage Examples

Simple Water Simulation

"Run a molecular dynamics simulation of a water molecule at 300K for 10000 steps"

Advanced Protein Simulation

"Set up a protein production simulation for 100 nanoseconds at physiological temperature 310K, using Amber19 force field with TIP3P-FB water model, 0.15M salt concentration, and GPU acceleration"

Membrane Protein Simulation

"Create a POPC membrane protein simulation for 50 nanoseconds with surface tension control"

📊 OpenMM Parameters Reference

Integrators

• LangevinMiddle - Langevin middle integrator (recommended)
• Verlet - Verlet integrator (NVE ensemble)
• Brownian - Brownian dynamics
• VariableLangevin - Variable step size Langevin
• VariableVerlet - Variable step size Verlet
• NoseHoover - Nose-Hoover thermostat

Force Fields

• Amber14: ["amber14-all.xml", "amber14/tip3pfb.xml"]
• Amber19: ["amber19-all.xml", "amber19/tip3pfb.xml"]
• CHARMM36: ["charmm36_2024.xml", "charmm36/water.xml"]

Water Models

• tip3p - TIP3P water model
• tip3pfb - TIP3P-FB water model (recommended)
• tip4pew - TIP4P-Ew water model
• spce - SPC/E water model

Platforms

• CUDA - NVIDIA GPU (fastest)
• OpenCL - General GPU
• CPU - CPU computation
• Reference - Reference implementation

Nonbonded Methods

• PME - Particle Mesh Ewald (recommended for periodic systems)
• NoCutoff - No cutoff (small systems)
• CutoffNonPeriodic - Non-periodic cutoff
• CutoffPeriodic - Periodic cutoff
• Ewald - Traditional Ewald summation

Constraints

• None - No constraints
• HBonds - Hydrogen bond constraints (recommended)
• AllBonds - All bond constraints
• HAngles - Hydrogen angle constraints

Barostats

• MonteCarloBarostat - Isotropic pressure control
• MonteCarloAnisotropicBarostat - Anisotropic pressure control
• MonteCarloMembraneBarostat - Membrane system pressure control

Precision

• mixed - Mixed precision (recommended)
• single - Single precision
• double - Double precision

🔧 Configuration

Environment variables:

export TASK_DATA_DIR="./simulation_data"
export MAX_CONCURRENT_TASKS=4
export DEFAULT_OPENMM_PLATFORM="CUDA"
export LOG_LEVEL="INFO"
export LOG_FILE="./mcp_server.log"

📁 Project Structure

openmm-mcp-server/
├── run_openmm_server.py      # Startup script
├── test_mcp_server.py        # Test script
├── requirements.txt          # Dependencies
├── README.md                 # English documentation
├── README_CN.md              # Chinese documentation
├── src/
│   ├── server_new.py         # Main server
│   ├── advanced_md_tools.py  # Advanced MD tools
│   ├── task_manager.py       # Task management
│   ├── openmm_engine.py      # OpenMM engine
│   ├── abacus_engine.py      # Abacus DFT engine
│   ├── config.py             # Configuration management
│   ├── tools/                # MCP tool implementations
│   ├── resources/            # MCP resource implementations
│   └── utils/                # Utility functions
├── tests/                    # Test files
├── examples/                 # Example code
├── docs/                     # Documentation
└── task_data/                # Task data directory (auto-created)

📚 Additional Documentation

• Installation Guide - Detailed installation instructions
• Usage Guide - Comprehensive usage examples
• Roo Code Integration - Detailed integration guide
• OpenMM Parameters - Complete parameter reference
• Project Analysis - Technical analysis and improvements

🔍 Troubleshooting

Common Issues

1. "OpenMM not found" warning

   • This is normal, server will run in mock mode
   • For actual simulations, install OpenMM: conda install -c conda-forge openmm

2. "command not found" error

   • Check if Python is in PATH
   • Verify project path is correct
   • Try using absolute paths

3. Permission errors

   • Ensure read/write permissions for project directory
   • Check if task_data directory is writable

Verify Configuration

# Test server startup
python run_openmm_server.py

# Test MCP functionality
python test_mcp_server.py

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

🆘 Support

If you encounter any issues:

1. Run the test script: python test_mcp_server.py
2. Review the documentation
3. Check log files (if configured)
4. Submit an issue on GitHub

📄 License

This project is licensed under the GNU General Public License v3.0.

---

Happy simulating! 🎉