README - openmm-mcp-server by phelanshao

OpenMM MCP Server

🧬 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

- Detailed installation instructions
- Comprehensive usage examples
- Detailed integration guide
- Complete parameter reference
- Technical analysis and improvements

🔍 Troubleshooting

Common Issues

"OpenMM not found" warning
- This is normal, server will run in mock mode
- For actual simulations, install OpenMM: conda install -c conda-forge openmm
"command not found" error
- Check if Python is in PATH
- Verify project path is correct
- Try using absolute paths
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

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

🆘 Support

If you encounter any issues:

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

📄 License

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

Happy simulating! 🎉