XTB MCP Server / XTB MCP 服务器

Created By

PhelanShao7 months ago

The XTB MCP Server is a Model Context Protocol (MCP) server that provides comprehensive tools for generating Extended Tight-Binding (XTB) quantum chemistry calculation input files. This server integrates seamlessly with AI assistants like Claude, Cursor, and Windsurf to enable intelligent quantum chemistry workflow automation.

# xtb-mcp-server

# quantum-chemistry

Overview Content Tools Comments

Content

XTB MCP Server / XTB MCP 服务器

English | 中文

English

Overview

Key Features

Complete XTB Input Generation: Support for all major calculation types (singlepoint, optimization, frequency, scan, MD)
Multiple XTB Methods: GFN0, GFN1, GFN2, and GFN-FF force field support
Structure Format Conversion: XYZ ↔ COORD ↔ Gaussian format handling
Advanced Sampling Methods: Metadynamics, pathfinder, normal mode following
Wavefunction Analysis: Orbital analysis, population analysis, spectroscopy
ONIOM Calculations: Multi-layer QM/MM calculations
Input Validation: Comprehensive validation with detailed error reporting
Rich Documentation: Extensive parameter documentation and examples

Project Structure

xtb-mcp-server/
├── main.py                     # MCP server entry point
├── requirements.txt            # Python dependencies
├── DEPLOYMENT_GUIDE.md         # Deployment instructions
├── PROJECT_SUMMARY.md          # Project overview
├── run_tests.py               # Test runner
├── test_mcp_functionality.py  # MCP functionality tests
├── final_validation.py        # Final validation script
├── xtb_input_generator/       # Core generator module
│   ├── __init__.py
│   ├── generator.py           # Main XTB input generator
│   └── structure_utils.py     # Structure format utilities
├── resources/                 # Template and documentation resources
│   ├── templates/             # XTB input templates
│   │   ├── singlepoint.xtb_tpl
│   │   ├── optimization.xtb_tpl
│   │   ├── frequency.xtb_tpl
│   │   ├── scan.xtb_tpl
│   │   ├── md.xtb_tpl
│   │   ├── sampling/          # Enhanced sampling templates
│   │   ├── wavefunction/      # Wavefunction analysis templates
│   │   └── advanced/          # Advanced calculation templates
│   ├── parameters/            # Method parameter documentation
│   │   ├── gfn0.md
│   │   ├── gfn1.md
│   │   └── gfn2.md
│   ├── formats/               # Input format specifications
│   │   └── input_spec.md
│   └── help/                  # Help documentation
│       └── faq.md
└── tests/                     # Comprehensive test suite
    ├── test_generator.py      # Generator functionality tests
    ├── test_structure_utils.py # Structure utility tests
    └── test_mcp_server.py     # MCP server integration tests

Installation

Clone the repository:

git clone <repository-url>
cd xtb-mcp-server

Install dependencies:
```
pip install -r requirements.txt
```
Run tests to verify installation:
```
python run_tests.py
```

MCP Configuration

Claude Desktop

Add to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "xtb-mcp-server": {
      "command": "python",
      "args": ["path/to/xtb-mcp-server/main.py"],
      "env": {}
    }
  }
}

Cursor

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "xtb-mcp-server": {
      "command": "python",
      "args": ["path/to/xtb-mcp-server/main.py"]
    }
  }
}

Windsurf

Configure in Windsurf settings:

{
  "mcp": {
    "servers": {
      "xtb-mcp-server": {
        "command": "python",
        "args": ["path/to/xtb-mcp-server/main.py"]
      }
    }
  }
}

Usage Examples

Example 1: Basic Geometry Optimization

User: "Generate XTB input files for water molecule geometry optimization using GFN2 method"

AI Assistant Response:

I'll generate XTB input files for water molecule geometry optimization using the GFN2 method.

[Uses generate_xtb_input_package tool]

Generated files:
- structure.xyz: Water molecule coordinates
- xcontrol: Optimization settings with GFN2 method
- run_xtb.sh: Execution script

The optimization will use tight convergence criteria and the GFN2 method for accurate results.

Example 2: Frequency Calculation with Solvent

User: "I need to run a frequency calculation for benzene in toluene solvent. Can you set up the input files?"

AI Assistant Response:

I'll set up frequency calculation input files for benzene in toluene solvent.

[Uses generate_xtb_input_package tool with frequency calculation type and toluene solvent]

Generated files include:
- Benzene structure in XYZ format
- xcontrol file with frequency calculation settings
- Toluene solvent model (GBSA)
- Temperature set to 298.15 K

The calculation will provide vibrational frequencies and thermodynamic properties.

Example 3: Enhanced Sampling Setup

User: "Set up a metadynamics simulation for conformational sampling of a flexible molecule"

AI Assistant Response:

I'll configure a metadynamics simulation for conformational sampling.

[Uses generate_enhanced_sampling_input tool]

Generated metadynamics setup:
- Collective variables: dihedral angles
- Gaussian height: 0.1 kcal/mol
- Gaussian width: 0.2 radians
- Deposition frequency: every 100 steps
- Temperature: 300 K

This will efficiently explore the conformational space of your molecule.

Example 4: Structure Format Conversion

User: "Convert this Gaussian input to XYZ format for XTB calculations"

AI Assistant Response:

I'll convert your Gaussian input file to XYZ format for XTB calculations.

[Uses convert_structure_file_format tool]

Conversion successful:
- Extracted molecular geometry from Gaussian input
- Generated clean XYZ format
- Preserved atomic coordinates and elements
- Ready for XTB calculations

The converted structure is now compatible with all XTB calculation types.

Available Tools

generate_xtb_input_package: Generate complete XTB input file packages
convert_structure_file_format: Convert between molecular structure formats
validate_xtb_input_files: Validate XTB input file syntax and parameters
generate_xcontrol_file: Generate XTB control files with specific settings
explain_xtb_parameters: Get detailed explanations of XTB parameters
generate_enhanced_sampling_input: Set up enhanced sampling calculations
generate_wavefunction_analysis_input: Configure wavefunction analysis
generate_oniom_input: Set up multi-layer ONIOM calculations
generate_spectroscopy_input: Configure spectroscopy calculations
analyze_trajectory: Analyze molecular dynamics trajectories

Resources

The server provides access to extensive documentation and templates:

Templates: Pre-configured input templates for all calculation types
Parameters: Detailed documentation for GFN0, GFN1, and GFN2 methods
Formats: Input format specifications and examples
Help: FAQ and troubleshooting guides

中文

概述

XTB MCP 服务器是一个模型上下文协议（MCP）服务器，为生成扩展紧束缚（XTB）量子化学计算输入文件提供全面的工具。该服务器与 Claude、Cursor 和 Windsurf 等 AI 助手无缝集成，实现智能量子化学工作流自动化。

主要功能

完整的 XTB 输入生成：支持所有主要计算类型（单点、优化、频率、扫描、分子动力学）
多种 XTB 方法：支持 GFN0、GFN1、GFN2 和 GFN-FF 力场
结构格式转换：XYZ ↔ COORD ↔ Gaussian 格式处理
高级采样方法：元动力学、路径搜索、正常模式跟踪
波函数分析：轨道分析、布居分析、光谱学
ONIOM 计算：多层 QM/MM 计算
输入验证：全面验证和详细错误报告
丰富文档：广泛的参数文档和示例

项目结构

xtb-mcp-server/
├── main.py                     # MCP 服务器入口点
├── requirements.txt            # Python 依赖
├── DEPLOYMENT_GUIDE.md         # 部署指南
├── PROJECT_SUMMARY.md          # 项目概述
├── run_tests.py               # 测试运行器
├── test_mcp_functionality.py  # MCP 功能测试
├── final_validation.py        # 最终验证脚本
├── xtb_input_generator/       # 核心生成器模块
│   ├── __init__.py
│   ├── generator.py           # 主要 XTB 输入生成器
│   └── structure_utils.py     # 结构格式工具
├── resources/                 # 模板和文档资源
│   ├── templates/             # XTB 输入模板
│   │   ├── singlepoint.xtb_tpl
│   │   ├── optimization.xtb_tpl
│   │   ├── frequency.xtb_tpl
│   │   ├── scan.xtb_tpl
│   │   ├── md.xtb_tpl
│   │   ├── sampling/          # 增强采样模板
│   │   ├── wavefunction/      # 波函数分析模板
│   │   └── advanced/          # 高级计算模板
│   ├── parameters/            # 方法参数文档
│   │   ├── gfn0.md
│   │   ├── gfn1.md
│   │   └── gfn2.md
│   ├── formats/               # 输入格式规范
│   │   └── input_spec.md
│   └── help/                  # 帮助文档
│       └── faq.md
└── tests/                     # 全面测试套件
    ├── test_generator.py      # 生成器功能测试
    ├── test_structure_utils.py # 结构工具测试
    └── test_mcp_server.py     # MCP 服务器集成测试

安装

克隆仓库：

git clone <repository-url>
cd xtb-mcp-server

安装依赖：
```
pip install -r requirements.txt
```
运行测试验证安装：
```
python run_tests.py
```

MCP 配置

Claude Desktop

在 Claude Desktop 配置文件（claude_desktop_config.json）中添加：

{
  "mcpServers": {
    "xtb-mcp-server": {
      "command": "python",
      "args": ["path/to/xtb-mcp-server/main.py"],
      "env": {}
    }
  }
}

Cursor

在 Cursor MCP 配置中添加：

{
  "mcpServers": {
    "xtb-mcp-server": {
      "command": "python",
      "args": ["path/to/xtb-mcp-server/main.py"]
    }
  }
}

Windsurf

在 Windsurf 设置中配置：

{
  "mcp": {
    "servers": {
      "xtb-mcp-server": {
        "command": "python",
        "args": ["path/to/xtb-mcp-server/main.py"]
      }
    }
  }
}

使用示例

示例 1：基本几何优化

用户： "为水分子生成使用 GFN2 方法的几何优化 XTB 输入文件"

AI 助手回应：

我将为水分子生成使用 GFN2 方法的几何优化 XTB 输入文件。

[使用 generate_xtb_input_package 工具]

生成的文件：
- structure.xyz：水分子坐标
- xcontrol：使用 GFN2 方法的优化设置
- run_xtb.sh：执行脚本

优化将使用紧收敛标准和 GFN2 方法以获得准确结果。

示例 2：溶剂中的频率计算

用户： "我需要在甲苯溶剂中对苯进行频率计算。你能设置输入文件吗？"

AI 助手回应：

我将为苯在甲苯溶剂中的频率计算设置输入文件。

[使用带有频率计算类型和甲苯溶剂的 generate_xtb_input_package 工具]

生成的文件包括：
- XYZ 格式的苯结构
- 带有频率计算设置的 xcontrol 文件
- 甲苯溶剂模型（GBSA）
- 温度设置为 298.15 K

计算将提供振动频率和热力学性质。

示例 3：增强采样设置

用户： "为柔性分子的构象采样设置元动力学模拟"

AI 助手回应：

我将为构象采样配置元动力学模拟。

[使用 generate_enhanced_sampling_input 工具]

生成的元动力学设置：
- 集体变量：二面角
- 高斯高度：0.1 kcal/mol
- 高斯宽度：0.2 弧度
- 沉积频率：每 100 步
- 温度：300 K

这将有效探索分子的构象空间。

示例 4：结构格式转换

用户： "将这个 Gaussian 输入转换为 XTB 计算的 XYZ 格式"

AI 助手回应：

我将把您的 Gaussian 输入文件转换为 XTB 计算的 XYZ 格式。

[使用 convert_structure_file_format 工具]

转换成功：
- 从 Gaussian 输入中提取分子几何
- 生成清洁的 XYZ 格式
- 保留原子坐标和元素
- 准备用于 XTB 计算

转换后的结构现在与所有 XTB 计算类型兼容。