orca-mcp-server

ORCA MCP Server

A Model Context Protocol (MCP) server for ORCA quantum chemistry software that provides intelligent tools for generating, validating, and optimizing ORCA input files.

Overview

The ORCA MCP Server is a comprehensive tool designed to assist quantum chemistry researchers and computational chemists in working with ORCA calculations. It provides intelligent assistance for:

• Input File Generation: Automatically generate ORCA input files based on molecular structures and calculation requirements
• Syntax Validation: Validate ORCA input file syntax and detect common errors
• Parameter Optimization: Recommend optimal basis sets, SCF settings, and memory configurations
• Convergence Diagnostics: Analyze failed calculations and suggest fixes
• Keyword Management: Suggest appropriate keywords and detect conflicts

Features

Core Functionality

• 🔧 Input File Generation: Create complete ORCA input files from molecular coordinates and calculation parameters
• ✅ Syntax Validation: Comprehensive validation of ORCA input file syntax with detailed error reporting
• 💡 Keyword Suggestions: Intelligent keyword recommendations based on calculation type and current settings
• 🎯 Parameter Optimization: Smart recommendations for basis sets, SCF settings, and memory allocation
• 🔍 Convergence Diagnostics: Analyze SCF convergence failures and provide targeted solutions

Supported Calculation Types

• Single Point Energy Calculations
• Geometry Optimizations
• Frequency Calculations
• Combined Optimization + Frequency
• TD-DFT (Time-Dependent DFT)
• MP2 and Coupled Cluster methods
• NMR and EPR calculations

Coordinate Format Support

• XYZ Coordinates: Standard Cartesian coordinates
• Internal Coordinates: Z-matrix format
• External Files: References to .xyz and .gzmt files

Installation

Prerequisites

• Node.js 18+
• npm or yarn
• TypeScript 5.0+

Install Dependencies

npm install

Build the Server

npm run build

Run Tests

npm test

Run with Coverage

npm run test:coverage

Usage

As an MCP Server

The server can be used with any MCP-compatible client. Configure your client to connect to this server using stdio transport.

Example configuration for Claude Desktop:

{
  "mcpServers": {
    "orca-mcp-server": {
      "command": "node",
      "args": ["path/to/orca-mcp-server/build/index.js"],
      "env": {}
    }
  }
}

Available Tools

generate_input_file

Generate a complete ORCA input file based on calculation parameters.

Parameters:

• calculation_type (string): Type of calculation ("single_point", "optimization", "frequency", etc.)
• charge (number): Molecular charge
• multiplicity (number): Spin multiplicity
• coordinates_xyz_or_internal (string, optional): Molecular coordinates
• keywords (array, optional): Additional ORCA keywords
• accuracy_level (string, optional): "low", "medium", or "high"
• blocks (object, optional): Custom parameter blocks

Example:

{
  "calculation_type": "optimization",
  "charge": 0,
  "multiplicity": 1,
  "coordinates_xyz_or_internal": "C 0.0 0.0 0.0\nH 0.0 0.0 1.0\nH 0.0 1.0 0.0\nH 1.0 0.0 0.0",
  "keywords": ["B3LYP", "def2-SVP"],
  "accuracy_level": "medium"
}

validate_input_syntax

Validate the syntax of an ORCA input file and detect common errors.

Parameters:

• inputContent (string): Complete ORCA input file content

Returns:

• Validation status and detailed error reports

suggest_keywords

Get keyword suggestions based on calculation type and current keywords.

Parameters:

• calculation_type (string): Intended calculation type
• current_keywords (array, optional): Already present keywords

Returns:

• Recommended and optional keywords with explanations

Programming Interface

You can also use the server components directly in your TypeScript/JavaScript code:

import { KeywordManager } from './src/core/keywordManager.js';
import { CoordinateProcessor } from './src/core/coordinateProcessor.js';
import { CalculationTemplateEngine } from './src/core/calculationTemplateEngine.js';

// Initialize components
const keywordManager = new KeywordManager();
const coordinateProcessor = new CoordinateProcessor();
const templateEngine = new CalculationTemplateEngine();

// Parse coordinates
const molecule = coordinateProcessor.parse_xyz_coordinates(
  'C 0.0 0.0 0.0\nH 0.0 0.0 1.0',
  0, 1
);

// Generate template
const template = templateEngine.generate_dft_template(molecule, 'B3LYP', 'def2-SVP');

// Validate keywords
const validation = await keywordManager.validate_keyword_combination(['B3LYP', 'def2-SVP', 'Opt']);

Architecture

Core Components

• KeywordManager: Manages ORCA keywords, validates combinations, and suggests missing keywords
• CoordinateProcessor: Handles molecular coordinate parsing and validation
• ParameterBlockManager: Generates ORCA parameter blocks (%scf, %basis, etc.)
• CalculationTemplateEngine: Creates calculation templates for different job types

Intelligent Components

• ParameterRecommendationEngine: Provides intelligent recommendations for basis sets, SCF settings, and memory
• ConvergenceDiagnostic: Analyzes convergence failures and suggests solutions
• ORCAInputValidator: Comprehensive input file validation

Type System

The server uses a comprehensive TypeScript type system defined in src/types/orca.types.ts that covers:

• Molecular structures and coordinate formats
• ORCA calculation types and parameters
• Validation results and error reporting
• Recommendation and diagnostic results

Examples

Basic DFT Optimization

// Generate input for geometry optimization
const result = await generateInputFile({
  calculation_type: "optimization",
  charge: 0,
  multiplicity: 1,
  coordinates_xyz_or_internal: `
    C 0.0 0.0 0.0
    H 0.0 0.0 1.0
    H 0.0 1.0 0.0
    H 1.0 0.0 0.0
    H -1.0 0.0 0.0
  `,
  accuracy_level: "medium"
});

console.log(result.content);
// Output:
// ! B3LYP-D3BJ def2-SVP Opt
// 
// %pal NProcs 2 end
// 
// * xyz 0 1
// C 0.0 0.0 0.0
// H 0.0 0.0 1.0
// H 0.0 1.0 0.0
// H 1.0 0.0 0.0
// H -1.0 0.0 0.0
// *

Heavy Element Calculation

// Get recommendations for heavy elements
const basisRecommendation = await recommendationEngine.recommend_basis_set(
  ['Au', 'Cl'],
  'high',
  2
);

console.log(basisRecommendation);
// Output:
// {
//   orbital_basis: "SARC-DKH-TZVP",
//   auxiliary_basis_jk: "SARC/JK",
//   auxiliary_basis_cosx: "SARC/J",
//   relativistic_method: "DKH",
//   reasoning: "High accuracy with heavy elements: SARC-DKH-TZVP with DKH relativistic treatment is recommended."
// }

SCF Convergence Troubleshooting

// Analyze convergence failure
const diagnosis = convergenceDiagnostic.analyze_scf_failure(`
  SCF NOT CONVERGED AFTER 125 ITERATIONS
  oscillating behavior in DIIS
  Energy change: 1.234e-03
`);

console.log(diagnosis);
// Output:
// {
//   problem_type: "SCF_OSCILLATION",
//   summary: "SCF convergence is likely hindered by oscillating behavior...",
//   recommendations: [
//     "Try damping: %scf DampFac 0.7 DampErr 0.05 end",
//     "Use a level shifter: %scf Shift Shift 0.5 Erroff 0.1 end"
//   ],
//   suggested_keywords_add: ["VerySlowConv"],
//   suggested_block_modifications: {
//     scf: "DampFac 0.7\nDampErr 0.05"
//   }
// }

Testing

The project includes comprehensive test coverage:

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Test Structure

• Unit Tests: Individual component testing
  • tests/core/: Core functionality tests
  • tests/intelligent/: AI/ML component tests
  • tests/validation/: Validation system tests
• Integration Tests: End-to-end workflow testing
  • tests/integration/: Complete workflow tests

Development

Project Structure

orca-mcp-server/
├── src/
│   ├── core/                 # Core functionality
│   │   ├── keywordManager.ts
│   │   ├── coordinateProcessor.ts
│   │   ├── parameterBlockManager.ts
│   │   └── calculationTemplateEngine.ts
│   ├── intelligent/          # AI/ML components
│   │   ├── parameterRecommendationEngine.ts
│   │   └── convergenceDiagnostic.ts
│   ├── validation/           # Validation systems
│   │   └── orcaInputValidator.ts
│   ├── types/               # TypeScript definitions
│   │   └── orca.types.ts
│   └── index.ts             # MCP server entry point
├── tests/                   # Test suites
├── build/                   # Compiled JavaScript
└── docs/                    # Documentation

Building

# Development build
npm run build

# Watch mode for development
npm run watch

Code Quality

The project uses:

• TypeScript for type safety
• Jest for testing
• ESLint for code linting
• Prettier for code formatting

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (npm test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Development Guidelines

• Write comprehensive tests for new features
• Follow TypeScript best practices
• Document public APIs
• Use meaningful commit messages
• Ensure backward compatibility

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• ORCA Quantum Chemistry Package - The quantum chemistry software this server supports
• Model Context Protocol - The protocol framework this server implements
• TypeScript Community - For excellent tooling and type system

Support

For questions, issues, or contributions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Join discussions in the project's discussion forum

Roadmap

Upcoming Features

• Context7 Integration: Enhanced documentation lookup and recommendations
• Basis Set Optimization: Automatic basis set selection based on molecular properties
• Job Monitoring: Integration with ORCA job status monitoring
• Result Analysis: Post-calculation analysis and visualization tools
• Template Library: Expandable library of calculation templates
• Performance Profiling: Calculation performance analysis and optimization

Long-term Goals

• Machine Learning Integration: ML-based parameter optimization
• Multi-software Support: Support for other quantum chemistry packages
• Web Interface: Browser-based interface for the MCP server
• Cloud Integration: Support for cloud-based calculations
• Collaborative Features: Multi-user calculation sharing and collaboration

---

Note: This is an independent project and is not officially affiliated with the ORCA quantum chemistry package developers.