🧬 gromacs-mcp

Drive GROMACS from any MCP client, in natural language.

Build topologies, solvate, add ions, preprocess, run simulations in the background, and post-process trajectories — all through the Model Context Protocol.

License: MIT Python 3.10+ MCP CI Code style: ruff

Why

Setting up and running a molecular-dynamics simulation is a long, error-prone chain of gmx sub-commands. gromacs-mcp exposes that pipeline as clean MCP tools so an LLM agent (Claude Code, Claude Desktop, or any MCP client) can plan and run the whole workflow while you supervise — without the agent ever blocking on a multi-hour mdrun.

Features

• Hybrid tool design — typed helpers for every common pipeline step plus a generic run_gmx escape hatch for any other gmx sub-command.
• Non-blocking simulations — mdrun_start launches in the background and returns a job id; poll progress (step / time / ns·day⁻¹ / ETA) with mdrun_status.
• Actionable errors — GROMACS Fatal error: blocks are extracted into a dedicated error_summary field, so the real cause survives output truncation.
• Project-scoped work dirs — each system lives in its own directory under a configurable root.
• Sandboxed file access — tool file paths stay inside the selected work directory by default.
• Zero-config discovery — finds gmx on PATH automatically (override with GMX_BIN).

Tools

Requirements

• GROMACS installed and gmx runnable (brew install gromacs, conda, or a source build).
• Python ≥ 3.10.
• An MCP client (e.g. Claude Code or Claude Desktop).

Install & run

The recommended way is uv — no global install needed:

# Run straight from GitHub (or a local checkout)
uvx --from git+https://github.com/Alierkn/gromacs-mcp gromacs-mcp

pipx install git+https://github.com/Alierkn/gromacs-mcp     # isolated, on PATH
# or
pip install git+https://github.com/Alierkn/gromacs-mcp
gromacs-mcp        # starts the stdio server

Connect it to your MCP client

Claude Code

claude mcp add gromacs --scope user -- \
  uvx --from git+https://github.com/Alierkn/gromacs-mcp gromacs-mcp

Then check: claude mcp list → gromacs: … ✔ Connected.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "gromacs": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Alierkn/gromacs-mcp", "gromacs-mcp"],
      "env": { "GMX_BIN": "/opt/homebrew/bin/gmx" }
    }
  }
}

Configuration

Relative workdir arguments resolve under GROMACS_MCP_ROOT; each subdirectory is one "project" (system) holding its .gro / .top / .tpr / .log files. By default, absolute work directories and file arguments that escape a work directory are rejected. Tool file paths must be relative to the selected workdir; hidden files, common secret files, and binary trajectory/run files are blocked by read_text_file and write_mdp.

Example prompt

"In workdir lyso, build a topology from 1aki.pdb with amber99sb-ildn / tip3p, put it in a 1.0 nm cubic box, solvate it, neutralise with ions, then run a short energy minimisation in the background and tell me when it's done."

The agent chains: pdb2gmx → editconf → solvate → grompp (ions) → genion → grompp (em) → mdrun_start → mdrun_status.

How it works

Each tool shells out to the local gmx binary via subprocess, captures stdout/stderr (GROMACS writes almost everything to stderr), and returns a structured result. Long simulations are detached with start_new_session=True; their metadata is persisted to a JSON registry so mdrun_status can report progress parsed from the live md.log. The registry is written atomically with a file lock, and job metadata records the process group and command hash to reduce stale-PID mistakes after server restarts.

The server also exposes MCP resources and prompts:

• Resources: gromacs://projects, gromacs://jobs, gromacs://templates/{name}
• Prompts: prepare_protein_md, debug_grompp_failure, basic_trajectory_analysis

Development

git clone https://github.com/Alierkn/gromacs-mcp && cd gromacs-mcp
uv sync --extra dev
uv run pytest        # tests that need gmx auto-skip if it is absent
uv run ruff check .
RUN_GROMACS_INTEGRATION=1 uv run pytest -m integration  # real GROMACS smoke test

See CONTRIBUTING.md. For implementation boundaries and release steps, see docs/ARCHITECTURE.md and docs/RELEASE.md.

Related

• vmd-mcp — companion MCP server for headless VMD analysis & rendering. Pair them: simulate with GROMACS, visualise with VMD.

License

MIT © Ali Erkan Ocaklı