mace-mcp-server

Run MACE atomistic simulations through AI assistants via the Model Context Protocol

Installation · Quick Start · Tools · Models · Development

Note

MACE is the most widely-used ML force field, with 11 foundation models covering 89 elements. This server bridges MACE with any MCP-compatible AI assistant, enabling researchers to run sub-second atomistic simulations through natural language.

• 11 foundation models covering 89 elements -- materials, molecules, and beyond
• 10 tools for energy, optimization, MD, vibrations, structure building, and more
• Sub-second inference with lazy model caching -- no 30-second reload penalty
• LLM-native errors with hint and next_action fields for self-correction
• All 3 MCP primitives -- Tools, Resources, and Prompts
• Structured output -- Pydantic-validated JSON with full outputSchema

---

Installation

pip install mace-mcp-server

Or run directly without installing:

uvx mace-mcp-server

More installation options

# With D3 dispersion correction 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]"

Quick Start

Claude Code

claude mcp add mace -- mace-mcp-server

VS Code / Cursor

The server auto-configures via the included .mcp.json. Open the project directory and the MCP server will be available.

Or add manually to your MCP settings:

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

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

---

What Can You Do?

Once connected, just ask your AI assistant:

"What model should I use for a periodic silicon slab?"

"Calculate the energy and forces of ethanol with MACE-OFF"

"Optimize this crystal structure, then run NVT MD at 500K for 200 steps"

"Compute the vibrational frequencies of water and show the thermodynamic properties"

"Build a 2x2x2 supercell of copper FCC and compute its equation of state"

---

Tools

Calculation

Tool	Description
single_point	Energy, forces, and stress evaluation
optimize	Geometry optimization (BFGS / FIRE)
molecular_dynamics	NVT / NPT / NVE simulations with trajectory output
vibrational_frequencies	Normal modes, IR intensities, and thermodynamics

Structure

Tool	Description
parse_structure	Read and analyze structure files (XYZ, CIF, POSCAR, PDB)
build_structure	Generate molecules, bulk crystals, and surfaces from scratch
convert_structure	Format conversion between XYZ, CIF, POSCAR, and PDB

Analysis

Tool	Description
equation_of_state	Fit E(V) curves for bulk modulus and equilibrium volume
extract_descriptors	Extract MACE learned atomic representations

Intelligence

Tool	Description
suggest_parameters	Recommend the right model, precision, and settings for your system

Tip

Not sure where to start? Use suggest_parameters -- it analyzes your system and recommends the right model, precision, and dispersion settings.

Resources

URI	Description
mace://models	Complete catalog of all foundation models
mace://models/{model_id}	Detailed info for a specific model
mace://catalog	List of available example structures
mace://examples/{type}	Example structures (water, ethanol, silicon, copper, NaCl, Cu surface)
mace://units	Unit conventions used across all calculations

Prompts

Prompt	Description
analyze_structure	Guided workflow: load a structure, run single-point, and interpret results
optimize_molecule	Guided workflow: build, optimize, and analyze a molecule end-to-end
md_simulation	Guided workflow: set up and run a molecular dynamics simulation

---

Foundation Models

Model	Elements	Domain	Best For
MACE-MPA-0 (default)	89	Materials	General-purpose crystals, surfaces, interfaces
MACE-MP-0	89	Materials	Original materials model (legacy)
MACE-OMAT-0	89	Materials	Phonons, mechanical properties
MACE-MATPES-PBE-0	89	Materials	Pure PBE functional accuracy
MACE-MATPES-r2SCAN-0	89	Materials	r2SCAN meta-GGA accuracy
MACE-MH-1	89	Cross-domain	Multi-functional, 7-head predictions
MACE-OFF23	10	Organic	Drug-like molecules, polymers (wB97M-D3BJ)
MACE-OMOL-0	83	Molecular	Organometallics, charged species
MACE-Polar-1	83	Molecular	Polarizability predictions
MACE-ANI-CC	4	High accuracy	Small H/C/N/O molecules (CCSD(T) quality)
Custom	varies	User-defined	Your own trained MACE models

Important

MACE-OFF23 already includes D3BJ dispersion (trained on wB97M-D3BJ). Never add D3 dispersion correction on top -- it will double-count.

---

Units

All calculations use consistent ASE units:

Quantity	Unit
Energy	eV
Force	eV/A
Distance	Angstrom
Stress	eV/A^3 (Voigt: xx, yy, zz, yz, xz, xy)
Frequency	cm^-1
Temperature	K

---

Architecture

src/mace_mcp_server/
  server.py          # FastMCP entry point + lifespan-managed model cache
  tools/             # Thin MCP wrappers (validate -> engine -> structured output)
  engine/            # All scientific logic (testable without MCP)
  schemas/           # Pydantic input/output models (auto JSON Schema)
  resources/         # URI-addressable data (model catalog, units, examples)
  prompts/           # Guided workflow templates

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 return structured output.

Development

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

# Run tests
pytest tests/

# Run server directly
PYTHONPATH=src python -m mace_mcp_server.server

# Inspect with MCP Inspector
npx -y @modelcontextprotocol/inspector mace-mcp-server

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Run tests (pytest tests/)
4. Submit a pull request

Citation

If you use this server in your research, please cite MACE:

@inproceedings{batatia2022mace,
  title={MACE: Higher Order Equivariant Message Passing Neural Networks for Fast and Accurate Force Fields},
  author={Batatia, Ilyes and Kov{\'a}cs, D{\'a}vid P{\'e}ter and Simm, Gregor NC and Ortner, Christoph and Cs{\'a}nyi, G{\'a}bor},
  booktitle={Advances in Neural Information Processing Systems},
  year={2022}
}

License

MIT -- Zicheng Zhao, Northeastern University