mace-mcp-server 0.1.0

MCP server for MACE machine learning interatomic potentials

mace-mcp-server

An MCP (Model Context Protocol) server that gives AI assistants direct access to MACE machine learning interatomic potentials. Run atomistic simulations -- energy calculations, geometry optimizations, molecular dynamics, vibrational analysis, and more -- through natural language.

Why?

MACE is the most widely-used ML force field with 11 foundation models covering 89 elements. This server bridges the gap between MACE's capabilities and AI assistants, enabling researchers to run sub-second atomistic simulations conversationally.

Features

• 10 Tools: Single-point energy, geometry optimization, molecular dynamics, vibrational frequencies, structure parsing/building/conversion, equation of state, descriptor extraction, parameter suggestion
• 4 Resources: Model catalog, individual model details, unit conventions, example structures
• 3 Prompts: Guided workflows for structure analysis, molecule optimization, MD simulation
• 11 Foundation Models: MACE-MPA-0, MACE-MP-0, MACE-OMAT-0, MACE-MATPES-PBE/r2SCAN, MACE-MH-1, MACE-OFF23, MACE-OMOL-0, MACE-Polar-1, MACE-ANI-CC, plus custom models
• All 3 MCP Primitives: Tools + Resources + Prompts
• Structured Output: Pydantic-validated JSON responses with full outputSchema
• LLM-Friendly Errors: Every error includes hint and next_action for self-correction
• Model Caching: Lazy loading with lifespan-managed cache (avoids 5-30s reload penalty)

Installation

# Standard install
pip install mace-mcp-server

# With D3 dispersion support
pip install mace-mcp-server[dispersion]

# From source (development)
git clone https://github.com/zichengzhao/mace-mcp-server
cd mace-mcp-server
pip install -e ".[dev]"

# Run directly with uvx (no install needed)
uvx mace-mcp-server

Quick Start

Claude Code

claude mcp add mace -- mace-mcp-server

Then ask:

• "Parse the structure at examples/water.xyz"
• "What model should I use for silicon?"
• "Calculate the energy of ethanol with MACE-OFF"
• "Optimize this crystal structure"
• "Run NVT MD at 500K for 200 steps"

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mace": {
      "command": "uvx",
      "args": ["mace-mcp-server"]
    }
  }
}

MCP Inspector

npx -y @modelcontextprotocol/inspector mace-mcp-server

Tools

Tool	Description	Category
single_point	Energy, forces, stress evaluation	Calculation
optimize	Geometry optimization (BFGS/FIRE)	Calculation
molecular_dynamics	NVT/NPT/NVE simulations	Calculation
vibrational_frequencies	Normal modes and thermodynamics	Calculation
parse_structure	Read and analyze structure files	Structure
build_structure	Generate molecules, crystals, surfaces	Structure
convert_structure	Format conversion (XYZ, CIF, POSCAR, PDB)	Structure
equation_of_state	Bulk modulus and equilibrium volume	Analysis
extract_descriptors	MACE learned atomic representations	Analysis
suggest_parameters	AI-powered parameter recommendation	Intelligence

Foundation Models

Model	Elements	Domain	Use Case
MACE-MPA-0 (default)	89	Materials	Crystals, surfaces, interfaces
MACE-OFF23	10	Organic	Drug-like molecules, polymers
MACE-OMOL-0	83	Molecular	Organometallics, charged species
MACE-ANI-CC	4	High accuracy	Small H/C/N/O molecules (CCSD(T))
MACE-OMAT-0	89	Materials	Phonons, mechanical properties
MACE-MH-1	89	Cross-domain	Multi-functional predictions

See mace://models resource for the complete catalog.

Units

All calculations use ASE's unit system:

• Energy: eV
• Force: eV/A
• Distance: Angstrom
• Stress: eV/A^3 (Voigt: [xx, yy, zz, yz, xz, xy])
• Frequency: cm^-1
• Temperature: Kelvin

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run with logging
PYTHONPATH=src python -m mace_mcp_server.server

Architecture

src/mace_mcp_server/
  server.py          # FastMCP entry point + lifespan
  tools/             # MCP tool wrappers (thin layer)
  resources/         # URI-addressable data (model catalog, units, examples)
  prompts/           # Workflow templates
  engine/            # Scientific logic (testable without MCP)
  schemas/           # Pydantic input/output models

The engine/ layer contains all scientific logic and is fully testable without MCP transport. Tools are thin wrappers that validate input, call the engine, and format structured output.

License

MIT