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:

```bash