Metadata-Version: 2.4
Name: mace-mcp-server
Version: 0.1.0
Summary: MCP server for MACE machine learning interatomic potentials
Author-email: Zicheng Zhao <zhao.ziche@northeastern.edu>
License-Expression: MIT
License-File: LICENSE
Keywords: atomistic,force-field,mace,materials-science,mcp,simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: ase>=3.22.0
Requires-Dist: mace-torch>=0.3.10
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: torch>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: dispersion
Requires-Dist: torch-dftd>=0.4.0; extra == 'dispersion'
Description-Content-Type: text/markdown

# mace-mcp-server

An MCP (Model Context Protocol) server that gives AI assistants direct access to [MACE](https://github.com/ACEsuit/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

```bash
# 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

```bash
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`:

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

### MCP Inspector

```bash
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

```bash
# 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
