gromacs-mcp 0.2.0

Model Context Protocol server that drives a local GROMACS installation — build, solvate, ionize, run simulations in the background, and analyse trajectories from any MCP client.

🧬 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.

---

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

Category	Tool	Purpose
Introspect	gmx_info	GROMACS version / build / binary path
	list_files	List files in a work directory
	read_text_file	Read an .mdp / .top / .log (clipped)
	write_mdp	Write an .mdp (or any text) file
MDP templates	write_em_mdp	Write a safe energy-minimisation template
	write_nvt_mdp	Write a safe NVT equilibration template
	write_npt_mdp	Write a safe NPT equilibration template
	write_md_mdp	Write a safe production-MD template
	validate_mdp	Check syntax and common MDP issues
Pipeline	pdb2gmx	Structure → topology + coordinates
	editconf	Define the simulation box
	solvate	Fill the box with solvent
	grompp	Preprocess → run input (.tpr)
	genion	Add neutralising / salt ions
	trjconv	Trajectory PBC / centering / conversion
Analysis	make_ndx	Create/edit GROMACS index files
	energy	Extract energy terms from .edr
	rms	RMSD analysis
	rmsf	RMSF analysis
	gyrate	Radius-of-gyration analysis
	hbond	Hydrogen-bond analysis
	sasa	Solvent-accessible surface area
	check	Validate GROMACS binary/text artefacts
Simulation	mdrun_start	Start a simulation in the background
	mdrun_status	Poll progress + log tail
	mdrun_list	List all background jobs
	mdrun_stop	Terminate a job (writes checkpoint)
	mdrun_logs	Read captured background-job logs
	mdrun_cleanup	Remove finished job records
	mdrun_forget	Remove one job record
Escape hatch	run_gmx	Any other gmx sub-command

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

Alternative: pip / pipx

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

Env var	Default	Meaning
GMX_BIN	auto (which gmx)	Path to the gmx executable
GROMACS_MCP_ROOT	~/gromacs-mcp/projects	Base dir for work directories
GROMACS_MCP_ALLOW_ABSOLUTE_WORKDIRS	unset	Set to 1 to allow absolute workdir values

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ı