# yusong652/yade-mcp [Health: Active]

**Category:** 🔬 Research  
**Repository:** https://github.com/yusong652/yade-mcp  
**GitHub Stars:** 15  
**Views:** 7  
**Installs:** 0  
**Upvotes:** 1  
**Directory Page:** https://allmcps.com/mcp/yusong652-yade-mcp

## Description
MCP server for YADE — open-source discrete element method (DEM) engine for granular and particle simulation. Browse API docs with BM25 search, execute code via synchronous REPL or async background tasks, monitor progress, and review task history.

## Tools
Capabilities this server exposes over MCP:

- **yade_browse_api** — Browse YADE's Python API as a YADE-native class tree.

The tree is rooted in YADE's real inheritance hierarchy: paths
mirror the class's __mro__ up to its category root. No
shortcuts — always drill through parents.
- **yade_query_api** — Search YADE API documentation by keywords (like grep).

Returns matching class/function names with descriptions ranked by relevance.
Use yade_browse_api for full documentation of a specific class.

When to use:
- You have keywords but don't know the exact class name
- Examples: "friction material", "gravity engine", "contact force",
  "triaxial stress", "sphere create", "hertz mindlin"

Related tools:
- yade_browse_api: Get full documentation for a known class path
- **yade_execute_task** — Submit a Python script for asynchronous execution in YADE.

Returns a task_id immediately; the script is queued and runs in
the background. Tasks run one at a time in submit order (they
share the YADE process and its single simulation state), so a
multi-stage pipeline can be submitted in one go — each stage
starts when the previous one finishes. Use the companion tools
to manage the task lifecycle:
- yade_check_task_status: poll output, progress, and final status
- yade_interrupt_task: stop a running task or cancel a queued one
- yade_list_tasks: browse task history (also shows queue order)

Use this for production simulation runs, long O.run() cycles,
and any operation that may take minutes or longer.
For quick queries and REPL-style testing, use yade_execute_code.
- **yade_check_task_status** — Check status and output for a submitted YADE task.
- **yade_list_tasks** — List tracked YADE tasks with pagination.

Tasks are listed newest first. Queued (pending) tasks run one at
a time in submit order, so among the pending entries the one
furthest down the list runs next.
- **yade_interrupt_task** — Stop a running YADE task, or cancel one still waiting in the queue.

A task that has not started yet is simply removed from the queue
and ends in status ``canceled`` (``method`` reports
``canceled_while_queued``). For a running task, two cancellation
paths are applied together by the bridge:

- ``flag_only`` — sets an interrupt flag that YADE's PyRunner
  tick observes between simulation iterations (graceful path
  for ``O.run`` tasks).
- ``flag_and_async_exc`` — in addition, injects a ``TaskInterrupt``
  exception into the script thread, so pure-Python deadloops
  with no ``O.run`` on the stack are terminated too.

The response ``method`` field reports which path ran. When
async-exc is refused (e.g. target thread is a Dummy-N
boost::python frame), ``async_exc_skipped_reason`` explains why.

Namespace after interrupt: the YADE ``__main__`` namespace is
shared between tasks and ``yade_execute_code`` calls. Any
variables the interrupted script had already defined —
including ``O`` state — are preserved. There's no need to
re-run the whole script to continue work: inspect state with
``yade_execute_code`` or resume via a fresh ``yade_execute_task``
that only runs the remaining logic.
- **yade_execute_code** — Execute Python code synchronously in the running YADE process.

Returns stdout immediately. Code runs in the YADE Python
environment where yade modules are already imported;
side effects persist.

This tool remains responsive EVEN WHILE a simulation task is
running (submitted via yade_execute_task). Use it as a live
REPL to inspect simulation state in real time — no need to
pre-script print statements.

Typical uses:
- Query simulation state: O.bodies count, current iteration
- Create/modify bodies, engines, interactions
- Read or set material properties
- Live inspection during a running simulation (e.g. check
  stress tensor, coordination number, energy balance,
  or capture viewport screenshots when GUI is available)
- Development and REPL-style testing

Unlike yade_execute_task, this tool is fire-and-return: the
response contains the full output. It is NOT tracked by
yade_list_tasks and cannot be interrupted or polled.

Timeout behaviour: on timeout the bridge attempts to abort the
running code. The response is an error envelope (``ok=false``)
whose ``error.code`` is one of:

- ``interrupted`` — the code was running a simulation cycle
  (``O.run``) and was paused cleanly at an iteration boundary.
  For long simulations or solving to equilibrium, switch to
  yade_execute_task — it tracks progress and stops cleanly via
  yade_interrupt_task.
- ``terminated`` — a non-cycle abort succeeded (async exception
  injection); the pump thread is free, but YADE state may be
  partially modified by the code that ran before the abort fired.
  Inspect state before retrying.
- ``timeout`` — abort failed (code stuck in a C extension, or
  nested inside a running task's PyRunner tick); the bridge may
  still be blocked. Restart if unresponsive.

WARNING: For anything expected to take more than a few seconds,
use yade_execute_task instead — it has proper cancellation via
yade_interrupt_task and does not leave state drift on timeout.
Also, do NOT write ``except BaseException:`` in your code; it
defeats bridge-initiated cancellation.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

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

## Documentation

## What yusong652/yade-mcp does

yusong652/yade-mcp gives MCP-compatible agents access to YADE’s Python API and a live YADE simulation environment. YADE is an open-source discrete element method engine used for granular and particle simulation. The server covers both API discovery and execution workflows, so an agent can find the relevant class before using it, test code in a session, or submit a longer simulation for background processing.

Its documentation functions expose YADE’s native class hierarchy and a keyword search over API documentation. The browser follows each class’s real inheritance path to its category root. Search uses BM25 ranking and returns matching class or function names with descriptions.

## How it works

The server provides seven MCP tools. `yade_browse_api` and `yade_query_api` do not require a bridge. The five execution tools communicate with the YADE MCP bridge running inside YADE’s Python environment.

`yade_execute_code` runs Python synchronously in the active YADE process. Calls share the YADE `__main__` namespace, so variables and simulation state persist between calls. The tool can inspect state while a background task is running, but it is intended for short operations and interactive testing.

For longer work, `yade_execute_task` submits a script and returns a task ID. Tasks run one at a time in submission order and share a single YADE process and simulation state. `yade_check_task_status` reports output, progress, and final status; `yade_list_tasks` provides paginated task history; and `yade_interrupt_task` stops a running task or removes a queued task. Interrupted scripts preserve state that was already created in the shared YADE namespace.

## Setup and configuration

Install YADE and `uv`, then register the MCP server with an MCP client using `uvx yade-mcp`. The repository gives commands for Claude Code, Codex CLI, and Gemini CLI, along with a generic MCP configuration using `uvx` as the command.

The bridge must be installed into the Python interpreter embedded by YADE, not an unrelated virtual environment. From the YADE console, install `yade-mcp-bridge` with that interpreter, restart YADE, and run:

```python
import yade_mcp_bridge
yade_mcp_bridge.start()
```

The bridge listens on port 9002 by default. Pass another port to `start(port=...)` and configure the MCP server with the matching `--bridge-url`. For containerized YADE, bind the bridge to `0.0.0.0` and publish the selected port.

## Tools and capabilities

- Browse YADE’s inheritance-based Python class tree.
- Search API documentation by terms such as friction material, gravity engine, or contact force.
- Execute short Python snippets and inspect persistent simulation state.
- Queue long simulations and multi-stage scripts.
- Poll output, review task history, and cancel queued or running work.
- Continue examining the YADE namespace after an interrupted task.

Use background tasks for operations expected to take more than a few seconds. A synchronous call that times out may leave YADE partially modified or the bridge unresponsive, depending on where interruption occurs. Code should not catch `BaseException`, because that can suppress bridge-initiated cancellation.

_Full upstream README: https://allmcps.com/mcp/yusong652-yade-mcp/readme_