Indranil2020/crystal_mcp_server

Crystal Structure Generator MCP Server

A comprehensive Model Context Protocol (MCP) server for generating accurate crystal structures for DFT, quantum chemistry, and condensed matter physics calculations.

Features

• ✨ Complete Coverage: All 230 space groups supported
• 🔬 PyXtal Integration: High-quality structure generation
• 📐 Structure Transformations: Supercells, slabs, surfaces
• 🔷 Symmetry Analysis: Spglib-powered symmetry detection
• 📁 Multiple Formats: CIF, POSCAR, XYZ, JSON export
• ✅ Comprehensive Validation: Distance checks, lattice validation
• ⚡ MLFF Optimization: Not implemented yet
• 🎯 Ground State Search: Not implemented yet

For the most accurate and complete capabilities list, see the .

Installation

Prerequisites

• Node.js 18+ and npm
• Python 3.8+ and pip
• Git

Quick Install

# Clone repository
git clone https://github.com/Indranil2020/crystal_mcp_server.git
cd crystal_mcp_server

# Install Node.js dependencies
npm install

# Install Python dependencies
pip install -r requirements.txt

# Build TypeScript
npm run build

# Run tests
npm test

Detailed Installation

1. Install Node.js Dependencies

npm install

This installs:

• @modelcontextprotocol/sdk
• zod (schema validation)
• python-shell (Python bridge)

2. Install Python Dependencies

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install packages
pip install -r requirements.txt

Required Python packages:

• pyxtal>=1.0.0 - Crystal structure generation
• pymatgen>=2024.1.1 - Materials analysis
• spglib>=2.5.0 - Symmetry operations
• ase>=3.22.0 - Atomic simulation environment

Optional MLFF packages (planned; MLFF not implemented yet):

• chgnet>=0.3.0 - CHGNet MLFF model
• matgl>=1.0.0 - M3GNet MLFF model
• mace-torch>=0.3.0 - MACE MLFF model

3. Build and Test

# Compile TypeScript
npm run build

# Run tests
npm test

# Lint code
npm run lint

Usage

Starting the Server

# Start with npm
npm start

# Or run directly
node dist/index.js

The server runs on stdio transport for MCP protocol communication.

Connect to an LLM

To use this server from an MCP-capable LLM client, configure the client to start the server with node dist/index.js and set the working directory to this repo. See for step-by-step setup examples.

Available Tools

1. generate_crystal

Generate a crystal structure with specified composition and space group.

{
  composition: ["Si", "Si"],
  space_group: 227,  // Diamond structure
  seed: 42
}

2. generate_space_group_scan

Scan multiple space groups to find stable structures.

{
  composition: ["Na", "Cl"],
  space_groups: [225, 216, 221],
  parallel: true
}

3. make_supercell

Create supercell from existing structure.

{
  structure_dict: {...},  // Structure object from generate_crystal
  scaling_matrix: [2, 2, 2]  // 2x2x2 supercell, or [[2,0,0],[0,2,0],[0,0,2]]
}

4. generate_slab

Generate surface slab for DFT calculations.

{
  structure_dict: {...},  // Structure object from generate_crystal
  miller_indices: [1, 0, 0],
  thickness: 5,  // Number of atomic layers
  vacuum: 15.0   // Vacuum padding in Angstroms
}

5. analyze_symmetry

Detect and analyze crystal symmetry.

{
  structure_dict: {...},  // Structure object
  symprec: 0.001,         // Symmetry precision tolerance
  detect_primitive: true  // Find primitive cell
}

6. validate_structure

Validate crystal structure quality.

{
  structure_dict: {...},  // Structure object
  checks: ["distances", "lattice", "stoichiometry"],  // Available checks
  min_distance: 1.5  // Minimum interatomic distance in Angstroms
}

7. optimize_structure_mlff (not implemented yet)

Planned MLFF optimization interface (CHGNet, M3GNet, MACE).

{
  structure_dict: {...},  // Structure object
  mlff_model: "chgnet",   // Options: "chgnet", "m3gnet", "mace"
  optimizer: "BFGS",      // Options: "BFGS", "FIRE", "LBFGS"
  fmax: 0.01,             // Force convergence criterion (eV/A)
  steps: 500              // Maximum optimization steps
}

8. ground_state_search (not implemented yet)

Planned ground state search across space groups.

{
  composition: ["Si", "Si"],
  space_groups: [227, 141, 194],
  mlff_model: "chgnet",
  num_structures_per_group: 5
}

9. export_structure

Export structure to multiple formats.

{
  structure_dict: {...},  // Structure object
  formats: ["cif", "poscar", "xyz", "json"],  // Output formats
  output_directory: "./output"  // Optional output path
}

Examples

Example 1: Generate Diamond Si

const result = await mcpClient.callTool("generate_crystal", {
  composition: ["Si", "Si"],
  space_group: 227,
  seed: 42
});

Example 2: Create Surface Slab

// First generate bulk structure
const bulk = await mcpClient.callTool("generate_crystal", {
  composition: ["Ti", "O", "O"],
  space_group: 136  // Rutile TiO2
});

// Then create (110) surface
const slab = await mcpClient.callTool("generate_slab", {
  structure_dict: bulk.structure,
  miller_indices: [1, 1, 0],
  thickness: 5,
  vacuum: 15.0,
  fix_bottom_layers: 2
});

Example 3: Ground State Search (not implemented yet)

const search = await mcpClient.callTool("ground_state_search", {
  composition: ["Si", "Si"],
  space_groups: [227, 141, 194],  // Diamond, I41/amd, P63/mmc
  num_structures_per_group: 10,
  mlff_model: "chgnet",
  optimization_settings: {
    optimizer: "BFGS",
    fmax: 0.01,
    steps: 500
  }
});

Architecture

crystal-mcp-server/
├── src/
│   ├── types/          # TypeScript type definitions
│   ├── utils/          # Utility functions
│   ├── python/         # Python backend scripts
│   ├── tools/          # MCP tool implementations
│   │   ├── generation/
│   │   ├── transformation/
│   │   ├── analysis/
│   │   ├── optimization/
│   │   └── export/
│   ├── server.ts       # MCP server setup
│   └── index.ts        # Entry point
├── tests/              # Test suites
├── docs/               # Documentation
└── package.json

Code Quality Standards

This project follows strict defensive programming practices:

• ✅ 100% type hints - All functions fully typed
• ✅ Defensive validation - Check inputs before processing
• ✅ Comprehensive tests - Unit and integration tests
• ✅ Clear error messages - Actionable suggestions included
• ✅ PEP 8 compliant - Python code follows standards
• ✅ ESLint compliant - TypeScript code follows standards

Performance

Benchmarks

Memory Requirements

• Minimal: 8 GB RAM, 4 cores
• Recommended: 16 GB RAM, 8 cores
• Large-scale: 32+ GB RAM, GPU support

Troubleshooting

Python Import Errors

# Verify Python packages
python -c "import pyxtal; print(pyxtal.__version__)"
python -c "import chgnet; print('CHGNet OK')"
python -c "import spglib; print('Spglib OK')"

MLFF Model Loading Fails (planned)

# Download CHGNet model
python -c "from chgnet.model import CHGNet; CHGNet.load()"

# Check GPU availability (optional)
python -c "import torch; print(torch.cuda.is_available())"

Permission Errors

# Make Python scripts executable
chmod +x src/python/*.py

Contributing

Contributions welcome! Please ensure:

1. All tests pass: npm test
2. Code is linted: npm run lint
3. Follow defensive programming guidelines
4. Add tests for new features
5. Update documentation

License

MIT License - see LICENSE file for details

Acknowledgments

Built with:

• PyXtal - Crystal structure generation
• Pymatgen - Materials analysis
• Spglib - Symmetry operations
• CHGNet - MLFF model
• MCP SDK - Protocol implementation

Support

• 📧 Email:
• 🐛 Issues: GitHub Issues
• 📖 Docs:

Status:

Version:

Last Updated: December 2025