mcp server

liggghts-mcp

MCP server wrapping LIGGGHTS DEM simulation — let LLM agents drive granular-flow simulations

boranC33/liggghts-mcpcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

~/Library/Application Support/Claude/claude_desktop_config.json

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

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 26, 2026

liggghts-mcp

An MCP server that lets LLM agents drive LIGGGHTS DEM simulations.

让 LLM agent 直接启动、监控和管理 LIGGGHTS 颗粒动力学仿真。

English

What Is This

A general-purpose MCP server around the liggghts binary. Instead of hand-writing shell commands and tracking background processes yourself, you describe the simulation task and the agent can call these generic tools:

Tool	Purpose
`validate_liggghts_bin(run_parse_probe, run_runtime_probe, mpi_ranks, mpirun)`	Check the configured `LIGGGHTS_BIN`, optional MPI launch path, safety limits, and optional self-contained `mesh/surface/stress` capability probes.
`estimate_case_cost(input_script, num_procs)`	Statically lint a deck, flag risky commands, and report rough run-size hints.
`validate_deck(input_script, execute, timeout, num_procs, mpirun)`	Statically validate a deck and optionally execute a tiny smoke/probe deck in a tempdir.
`create_dem_case(case_type, name, particle_count, ...)`	Generate structured starter decks for angle-of-repose, box-settling, and simple silo-discharge workflows, optionally writing or launching the case.
`create_advanced_dem_template(template_type, name, particle_count, ...)`	Generate advanced scaffolds for inclined chute, rotating drum, direct shear cell, and hopper-flow workflows.
`validate_case_assets(run_id, case_dir, deck_relpath, ...)`	Check a case deck, referenced files, missing assets, file hashes, and STL/OBJ mesh bounds.
`ensure_standard_outputs(input_script, run_id, write_back, ...)`	Add common thermo, custom dump, and optional VTK dump commands before the first run/minimize command.
`start_simulation(input_script, num_procs, name, overwrite, mpirun)`	Launch a run from inline LIGGGHTS deck text.
`start_parameter_sweep(template, parameters, name_prefix, num_procs, overwrite, mpirun)`	Render `{{param}}` deck templates and launch one run per parameter set.
`start_calibration_sweep(template, parameters, targets, ...)`	Launch a parameter sweep with calibration target metadata attached.
`start_from_file(input_path, num_procs, name, overwrite, mpirun)`	Launch a run from an existing input deck file.
`clone_run(run_id, new_name, replacements, append_text, deck_relpath, num_procs, overwrite, mpirun)`	Copy an existing run, edit its deck, and launch the clone.
`resume_from_restart(source_run_id, restart_relpath, new_name, continuation_script, run_steps, ...)`	Build and optionally launch a continuation case from a restart file.
`start_from_dir(case_dir, deck_relpath, name, num_procs, link_mode, overwrite, mpirun)`	Snapshot a whole case directory, then run a deck inside that isolated snapshot.
`prepare_batch(cases, batch_id, overwrite, validate)`	Prepare queued run directories from inline decks, templates, standard cases, or advanced scaffolds.
`start_batch(batch_id, max_start, num_procs, mpirun)`	Start queued cases from a prepared batch while respecting concurrency limits.
`batch_status(batch_id)`	Summarize queued/running/finished states for a prepared batch.
`list_batches()`	List prepared batch manifests.
`check_status(run_id)`	Return running/finished/unknown status, exit code, and the last log line.
`read_log(run_id, tail)`	Read the tail of `log.run`.
`list_outputs(run_id, patterns, include_bookkeeping)`	List dumps, trajectories, CSV/JSON summaries, logs, VTK files, restart files, and other matching outputs.
`list_output_details(run_id, patterns, include_bookkeeping)`	List outputs with relative path, kind, size, and modified timestamp.
`list_dumps(run_id)`	Convenience wrapper for dump/VTK/restart/post files.
`read_output(run_id, relpath, offset, max_bytes)`	Safely read a bounded text window from a run output file.
`parse_log(run_id, max_bytes)`	Extract warnings, errors, final thermo row, and loop summary from `log.run`.
`analyze_dump_metrics(run_id, input_relpath, max_frames, ...)`	Parse LIGGGHTS/LAMMPS custom dumps and export frame metrics as JSON/CSV.
`summarize_run(run_id, max_outputs)`	Combine status, parsed log, and output metadata for one run.
`compare_runs(run_ids)`	Compare compact summaries for multiple runs.
`evaluate_calibration(run_ids, targets, analyze_dumps, ...)`	Score runs against target metrics from summaries and dump metrics.
`suggest_calibration_cases(best_parameters, parameter_bounds, ...)`	Suggest next-round parameter cases around the current best calibration point.
`validate_visualization_tools()`	Check OVITO Python, OVITO GUI, ParaView, `pvpython`, and `pvbatch` availability.
`convert_dump_with_ovito(run_id, input_relpath, output_relpath, export_format)`	Convert dumps/trajectories through OVITO into VTK/XYZ/LAMMPS-dump style outputs.
`render_with_ovito(run_id, input_relpath, output_relpath)`	Render a PNG screenshot from a dump/trajectory through OVITO.
`render_with_paraview(run_id, input_relpath, output_relpath)`	Render a PNG screenshot from VTK/VTP/VTU/CSV data through ParaView.
`collect_run_artifacts(run_id, patterns, artifact_dir, mode)`	Collect simulation and visualization outputs into `artifacts/` with a manifest.
`summarize_visual_outputs(run_id)`	List generated screenshots, animations, converted data, and visualization files.
`generate_run_report(run_id, include_dump_metrics, ...)`	Generate reproducible JSON and Markdown reports with status, logs, assets, metrics, and visualization outputs.
`list_runs()`	List known run directories and their persisted status.
`stop_simulation(run_id)`	Terminate a running simulation process group and record that the stop was user-requested.

Each run lives in its own directory under ~/liggghts_runs/<run_id>/ with input.in, log.run, pid, cmd, status.json, exit_code, plus whatever LIGGGHTS writes. The wrapper persists the child exit code, so completed runs remain inspectable after the MCP server restarts.

The server also exposes MCP resources:

Resource	Purpose
`liggghts://config`	Current binary, run root, and safety configuration.
`liggghts://runs`	Known runs.
`liggghts://runs/{run_id}/status`	One run's status.
`liggghts://runs/{run_id}/summary`	One run's status/log/output summary.
`liggghts://runs/{run_id}/outputs`	One run's output file metadata.
`liggghts://runs/{run_id}/input`	The run input deck.
`liggghts://runs/{run_id}/log`	Tail of `log.run`.

Bundled prompts provide starting points for common workflows: angle_of_repose_case, silo_discharge_case, mesh_wall_probe, and parameter_sweep.

Prerequisites

LIGGGHTS binary. Install one from your package manager or build from https://github.com/CFDEMproject/LIGGGHTS-PUBLIC.

The server reads LIGGGHTS_BIN and defaults to /usr/local/bin/liggghts.
Python 3.10+ with pip / venv.
MPI if you want num_procs > 1; the server launches mpirun -np N "$LIGGGHTS_BIN" -in input.in.
Optional visualization tools:
- OVITO Python module, available to python3 or configured with OVITO_PYTHON.
- ParaView command-line tools, especially pvpython or pvbatch, for VTK rendering.

MPI Scheduling

MPI here means multiple LIGGGHTS ranks, not one process automatically using many threads. For example:

mpirun -np 4 "$LIGGGHTS_BIN" -in input.in

Choose rank counts that fit the host. A conservative first rule is to avoid requesting more total ranks than available CPU cores unless you intentionally want oversubscription.

Install

git clone https://github.com/boranC33/liggghts-mcp
cd liggghts-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

Wire It Into Claude Code

claude mcp add -s user liggghts -- \
  /absolute/path/to/liggghts-mcp/.venv/bin/python \
  /absolute/path/to/liggghts-mcp/server.py

Verify:

claude mcp list
# liggghts: ... - ✓ Connected

Reloading After An Upgrade

After git pull or any code change, restart the MCP server and open a fresh Claude Code session:

claude mcp remove liggghts -s user
claude mcp add -s user liggghts -- \
  /absolute/path/to/liggghts-mcp/.venv/bin/python \
  /absolute/path/to/liggghts-mcp/server.py

If an older stdio child is still alive, kill it before re-adding:

pgrep -af 'liggghts-mcp.*server.py'

`LIGGGHTS_BIN` Must Be In The MCP Startup Environment

Setting LIGGGHTS_BIN only in your interactive shell may not reach the MCP child process. Either install LIGGGHTS at the default path, or pass the env var when registering the server:

claude mcp add -s user liggghts \
  --env LIGGGHTS_BIN=/opt/liggghts/bin/liggghts \
  -- /absolute/path/to/liggghts-mcp/.venv/bin/python \
     /absolute/path/to/liggghts-mcp/server.py

If a run fails to launch, call validate_liggghts_bin() first. For stricter mesh-wall capability checks, pass run_parse_probe=True and run_runtime_probe=True; both probes use self-contained temporary decks and do not depend on any external project directory.

Usage Examples

In a Claude Code session, you can ask:

"Run an angle-of-repose test with 10k 2 mm particles falling onto a floor."
"Create a structured box_settle starter case with 5k particles, validate its assets, then launch it."
"Create an inclined chute advanced template at 28 degrees and run a small smoke case."
"Launch ~/cases/silo.in, name it silo_v1, and don't wait."
"Sweep friction coefficient from 0.2 to 0.6 over 5 generic cases."
"Start a calibration sweep and rank the runs by target solid fraction."
"Prepare a batch of 12 cases and start only the first 3 now."
"Resume silo_v1 from the newest restart for another 50k steps."
"Is silo_v1 done yet? Show the last 50 log lines."
"Add standard dump outputs to this deck, run it, convert the dump with OVITO, then render a preview image."
"Analyze particles.lammpstrj into CSV/JSON metrics and generate a final run report."
"Render the VTK outputs from silo_v1 with ParaView and collect artifacts."

The agent can generate starter cases, validate assets, write or reuse decks, call start_simulation, resume from restarts, poll check_status, read logs, summarize outputs, analyze dumps, convert dumps, render OVITO/ParaView previews, and generate final reports.

Configuration

Env var	Default	Purpose
`LIGGGHTS_BIN`	`/usr/local/bin/liggghts`	LIGGGHTS executable
`LIGGGHTS_RUNS`	`~/liggghts_runs`	Run directory root
`LIGGGHTS_READ_ONLY`	`0`	Disable mutating tools such as start/stop/clone/sweep.
`LIGGGHTS_ALLOW_OVERWRITE`	`0`	Allow `overwrite=True` to delete an existing finished run dir.
`LIGGGHTS_MAX_RANKS`	unset	Maximum MPI ranks accepted by tools/probes.
`LIGGGHTS_MAX_CONCURRENT_RUNS`	unset	Maximum simultaneously running cases.
`LIGGGHTS_ALLOWED_CASE_ROOTS`	unset	`:`-separated source roots for `start_from_file` / `start_from_dir`.
`LIGGGHTS_MAX_SWEEP_CASES`	`32`	Maximum cases created by one parameter sweep.
`LIGGGHTS_MAX_BATCH_CASES`	`64`	Maximum cases prepared by one batch manifest.
`LIGGGHTS_MAX_READ_BYTES`	`262144`	Maximum bytes returned by output/log readers.
`LIGGGHTS_MAX_ANALYSIS_BYTES`	`33554432`	Maximum bytes read from a dump by analysis/report tools.
`LIGGGHTS_ALLOW_DECK_SHELL`	`0`	Allow LIGGGHTS deck `shell` commands. Disabled by default.
`LIGGGHTS_VALIDATE_TIMEOUT_MAX`	`120`	Maximum timeout accepted by `validate_deck(execute=True)`.
`LIGGGHTS_VIS_TIMEOUT`	`300`	Maximum seconds for one conversion/render command.
`OVITO_PYTHON`	auto	Python executable that can `import ovito`.
`OVITO_BIN`	auto	Optional OVITO GUI executable for capability reporting.
`PARAVIEW_BIN`	auto	Optional ParaView GUI executable for capability reporting.
`PVPYTHON_BIN`	auto	ParaView Python executable used by `render_with_paraview`.
`PVBATCH_BIN`	auto	ParaView batch executable used when `use_pvbatch=True`.

LIGGGHTS_BIN may be an absolute path, a ~/... path, or a bare executable name resolvable from the MCP server's PATH.

Custom list_outputs(patterns=...) glob patterns are intentionally confined to the selected run directory: absolute patterns and patterns containing .. are rejected.

Decks containing LIGGGHTS shell commands are rejected by default. Set LIGGGHTS_ALLOW_DECK_SHELL=1 only for trusted decks.

Docker

Build the server image:

docker build -t liggghts-mcp .

Run with host LIGGGHTS and a persistent run directory:

docker run --rm -i \
  -e LIGGGHTS_BIN=/usr/local/bin/liggghts \
  -v /usr/local/bin/liggghts:/usr/local/bin/liggghts:ro \
  -v "$HOME/liggghts_runs:/root/liggghts_runs" \
  liggghts-mcp

Bundled Libraries

If your liggghts binary needs shared libraries that your loader cannot find, drop those .so files into lib/ and the server will inject LD_LIBRARY_PATH for the child process. Library files are gitignored.

Tests

python -m unittest

Known Limitations

No GPU support is provided by this wrapper; behavior depends on the LIGGGHTS binary you point it at.
stop_simulation sends SIGTERM to the process group, then SIGKILL if needed. Some MPI launchers may need custom cleanup outside the wrapper.

License

MIT. LIGGGHTS itself is GPL-2; this wrapper does not link against LIGGGHTS code, it only spawns the binary as a subprocess.

中文

这是什么

这是一个通用的 liggghts MCP server。它不包含个人项目流水线；负责启动、监控、停止、检查和汇总通用 LIGGGHTS 仿真。

工具	用途
`validate_liggghts_bin`	检查 `LIGGGHTS_BIN`、MPI 启动路径，以及可选的 `mesh/surface/stress` 自包含 probe。
`estimate_case_cost`	静态检查 deck，提示风险命令和大致规模。
`validate_deck`	静态验证 deck，可选在临时目录执行小型 smoke/probe。
`create_dem_case`	生成休止角、盒内沉降、简单料仓卸料等结构化 starter case，并可选择写入或启动。
`create_advanced_dem_template`	生成斜槽、转鼓、直剪盒、料斗流等高级 scaffold。
`validate_case_assets`	检查 case deck、引用文件、缺失资产、文件哈希和 STL/OBJ 网格边界。
`ensure_standard_outputs`	在首个 `run` / `minimize` 前补充常用 thermo、dump 和可选 VTK 输出命令。
`start_simulation`	从 deck 文本启动仿真。
`start_parameter_sweep`	渲染 `{{param}}` 模板并启动参数扫描。
`start_calibration_sweep`	启动带目标指标元数据的标定参数扫描。
`start_from_file`	从已有输入文件启动仿真。
`clone_run`	复制已有 run、修改 deck 并启动新 run。
`resume_from_restart`	从已有 restart 文件准备并可选启动续算 run。
`start_from_dir`	快照整个 case 目录，再在隔离副本里运行指定 deck。
`prepare_batch`	从 deck、模板、标准 case 或高级 scaffold 准备 queued 批处理 case。
`start_batch`	按并发限制启动批处理中的 queued case。
`batch_status`	汇总批处理 case 的 queued/running/finished 状态。
`list_batches`	列出已准备的批处理 manifest。
`check_status`	查询运行状态、退出码和最后一行日志。
`read_log`	读取 `log.run` 末尾。
`list_outputs`	列出输出文件、日志、dump、restart、CSV/JSON、VTK 等。
`list_output_details`	列出输出文件的相对路径、类型、大小和修改时间。
`list_dumps`	只列 dump / VTK / restart / post 输出。
`read_output`	安全读取 run 目录内输出文件的一段文本。
`parse_log`	从 `log.run` 提取 warning/error、最后 thermo 行和 loop summary。
`analyze_dump_metrics`	解析 LIGGGHTS/LAMMPS custom dump，并导出逐帧 JSON/CSV 指标。
`summarize_run`	汇总单个 run 的状态、日志和输出。
`compare_runs`	对比多个 run 的摘要。
`evaluate_calibration`	按目标指标对多个 run 打分排序。
`suggest_calibration_cases`	围绕当前最优参数建议下一轮标定 case。
`validate_visualization_tools`	检查 OVITO Python、OVITO、ParaView、`pvpython` 和 `pvbatch`。
`convert_dump_with_ovito`	使用 OVITO 将 dump/轨迹转换为 VTK/XYZ/其他格式。
`render_with_ovito`	使用 OVITO 从 dump/轨迹渲染 PNG 预览图。
`render_with_paraview`	使用 ParaView 从 VTK/VTP/VTU/CSV 渲染 PNG 预览图。
`collect_run_artifacts`	将仿真和可视化输出收集到 `artifacts/` 并生成 manifest。
`summarize_visual_outputs`	汇总截图、动画、转换文件和可视化脚本。
`generate_run_report`	生成包含状态、日志、资产、指标和可视化结果的 JSON/Markdown 报告。
`list_runs`	列出所有已知 run。
`stop_simulation`	停止正在运行的仿真，并记录这是用户主动停止。

每个 run 位于 ~/liggghts_runs/<run_id>/，包含 input.in、log.run、 pid、cmd、status.json、exit_code 以及 LIGGGHTS 自己写出的文件。退出码会持久化，所以 MCP 重启后仍能检查已完成 run。

同时提供 MCP resources：liggghts://config、liggghts://runs、 liggghts://runs/{run_id}/status、summary、outputs、input 和 log。内置 prompts 包括 angle_of_repose_case、silo_discharge_case、 mesh_wall_probe 和 parameter_sweep。

安装和接入

git clone https://github.com/boranC33/liggghts-mcp
cd liggghts-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

claude mcp add -s user liggghts -- \
  /绝对路径/liggghts-mcp/.venv/bin/python \
  /绝对路径/liggghts-mcp/server.py

环境变量

环境变量	默认值	用途
`LIGGGHTS_BIN`	`/usr/local/bin/liggghts`	LIGGGHTS 可执行文件
`LIGGGHTS_RUNS`	`~/liggghts_runs`	run 目录根路径
`LIGGGHTS_READ_ONLY`	`0`	禁用启动、停止、clone、sweep 等修改型工具。
`LIGGGHTS_ALLOW_OVERWRITE`	`0`	允许 `overwrite=True` 删除已有已结束 run 目录。
`LIGGGHTS_MAX_RANKS`	未设置	限制最大 MPI ranks。
`LIGGGHTS_MAX_CONCURRENT_RUNS`	未设置	限制同时运行的 case 数。
`LIGGGHTS_ALLOWED_CASE_ROOTS`	未设置	限制 `start_from_file` / `start_from_dir` 的来源根目录。
`LIGGGHTS_MAX_SWEEP_CASES`	`32`	单次参数扫描最多 case 数。
`LIGGGHTS_MAX_BATCH_CASES`	`64`	单个批处理 manifest 最多准备的 case 数。
`LIGGGHTS_MAX_READ_BYTES`	`262144`	输出/日志读取最多返回字节数。
`LIGGGHTS_MAX_ANALYSIS_BYTES`	`33554432`	指标分析/报告工具最多读取 dump 的字节数。
`LIGGGHTS_ALLOW_DECK_SHELL`	`0`	是否允许 deck 中的 `shell` 命令；默认拒绝。
`LIGGGHTS_VALIDATE_TIMEOUT_MAX`	`120`	`validate_deck(execute=True)` 可接受的最大 timeout。
`LIGGGHTS_VIS_TIMEOUT`	`300`	单个转换/渲染命令的最大秒数。
`OVITO_PYTHON`	自动	能够 `import ovito` 的 Python 可执行文件。
`OVITO_BIN`	自动	可选 OVITO GUI 命令，仅用于能力检查。
`PARAVIEW_BIN`	自动	可选 ParaView GUI 命令，仅用于能力检查。
`PVPYTHON_BIN`	自动	`render_with_paraview` 使用的 ParaView Python。
`PVBATCH_BIN`	自动	`use_pvbatch=True` 时使用的 ParaView batch 命令。

LIGGGHTS_BIN 可以是绝对路径、~/... 路径，或 MCP server 启动环境 PATH 中能找到的可执行文件名。

自定义 list_outputs(patterns=...) glob 会被限制在对应 run 目录内；绝对路径和包含 .. 的 pattern 会被拒绝。

默认会拒绝包含 LIGGGHTS shell 命令的 deck；只有确认 deck 可信时才设置 LIGGGHTS_ALLOW_DECK_SHELL=1。

如果 LIGGGHTS_BIN 不是默认路径，注册 MCP 时传入：

claude mcp add -s user liggghts \
  --env LIGGGHTS_BIN=/opt/liggghts/bin/liggghts \
  -- /绝对路径/liggghts-mcp/.venv/bin/python \
     /绝对路径/liggghts-mcp/server.py

升级后需要 remove/add MCP，并新开 Claude Code 会话；如果旧的 server.py stdio 子进程还在，先手动 kill 再重新添加。

测试

python -m unittest

liggghts-mcp

Set up

README

liggghts-mcp

English

What Is This

Prerequisites

MPI Scheduling

Install

Wire It Into Claude Code

Reloading After An Upgrade

LIGGGHTS_BIN Must Be In The MCP Startup Environment

Usage Examples

Configuration

Docker

Bundled Libraries

Tests

Known Limitations

License

中文

这是什么

安装和接入

环境变量

测试

`LIGGGHTS_BIN` Must Be In The MCP Startup Environment