fairchem-mcp

fairchem-mcp

An agent-steerable MCP server for FAIRChemand ASE simulations.

Most LLM-driven simulation today is batch: the agent writes a script, runs it,waits, and reads the output. fairchem-mcp makes it interactive. The model isloaded once and kept resident; relaxations and MD run in the background; and theagent can watch a simulation as it runs and steer it mid-flight — switch theoptimizer when it stalls, tighten fmax, change temperature, pause, or abort.

Why

• Resident model. Load a UMA/eSEN model once; reuse it across every call. Noreloading the model (seconds–minutes) on each run.
• Live monitoring. get_status returns step, energy, max force, and atrend verdict (decreasing / plateaued / stuck / diverging) so theagent can decide whether to intervene.
• Mid-flight steering. steer can pause / resume / abort, set_fmax,switch_optimizer, or set_temperature on a running job. Switching optimizercarries the atomic positions over — it just rebuilds the driver.
• Hybrid namespace. High-level tools (start_relaxation, …) and theexecute / inspect_expr escape hatch share one Python namespace, so theagent can drop to raw Python on the very same live Atoms.
• Code awareness. introspect reads the installed API (real signatures anddocstrings) and live objects via jedi — not possibly-stale docs.

Install

pip install -e .            # core: mcp + ase + jedi (works with EMT)
pip install -e ".[fairchem]"  # add FAIRChem (torch + models) for UMA/eSEN

FAIRChem is optional. Every tool except load_model works with a plain ASEcalculator (attach_emt), so you can develop and test without a GPU or model.

Register with Claude Code

Add to your MCP config (see examples/claude_mcp_config.json):

{
  "mcpServers": {
    "fairchem": { "command": "fairchem-mcp" }
  }
}

Tools

Resources: sim://models, sim://job/{id}/status, sim://job/{id}/trajectory.

Example flow

attach_emt()                      -> calc_1
build_structure({"kind":"bulk","name":"Cu","crystalstructure":"fcc",
                 "a":3.6,"repeat":[2,2,2],"rattle":0.2})  -> struct_1
start_relaxation("struct_1","calc_1",optimizer="FIRE",fmax=0.01)  -> job_1
get_status("job_1")               -> {status:"running", trend:{label:"stuck", ...}}
steer("job_1","switch_optimizer",optimizer="LBFGS")
get_status("job_1")               -> {status:"converged", ...}
introspect("atoms", live=True)    -> live object signature/docstring

Finding multiple relaxed geometries

start_minima_search finds several distinct local minima of the PES — usefulfor surface adsorption sites, cluster isomers, or conformers. It relaxesrepeatedly from the starting structure on a PES biased to repel the minimaalready found, then polishes each escape on the true PES:

• kernel="flooding" (default) adds Gaussian bumps (sigma Å, amplitude eV);kernel="deflation" adds inverse-distance poles (eta, power). Both are bestfor fixed-frame problems (an adsorbate on a frozen slab, an anchoredconformer).
• kernel="basinhopping" (random kick + relax + Metropolis accept) is the righttool for free clusters / nanoparticles, whose rigid-body rotation defeats aspatial bias. Pair it with comparator="fingerprint" (see below).
• New minima are deduplicated by energy (energy_tol) plus a structurecomparator: "rmsd" (raw coords, frame-dependent — fine for a fixed frame) or"fingerprint" (sorted pairwise distances; rotation/translation/permutationinvariant — use for free clusters and molecules, or rotated copies getmiscounted as distinct). Each accepted minimum is registered as its ownstructure.

This reuses the escape mechanism from POUNCE's find_minima (deflation /flooding) but drives it with ASE's gradient optimizers — the right inner solverfor a PES — so each escape relaxation is a normal steerable job (watch the trend,switch_optimizer, set_fmax, pause/abort). POUNCE's interior-point solver isdeliberately not used as the inner relaxer.

Examples

examples/catalysis/ has four end-to-end catalysisworkflows — adsorption energy, adsorption-site search, diffusion-barrier NEB, andsurface-stability phonons — each as a runnable script and an MCP tool-callwalkthrough. They run on EMT out of the box; set FAIRCHEM_MCP_EXAMPLE_MODEL forUMA.

Safety

execute / inspect_expr run arbitrary Python in-process. This is a trustedlocal developer tool — do not expose it to untrusted input or over a network.

Notes

• Only one job runs at a time (serializes model/GPU access).
• All optimizers/integrators use logfile=None; the stdio transport reservesstdout for the MCP protocol.