MCP server for YADE — open-source DEM engine. Browse API docs, run simulations, manage tasks.
io.github.yusong652/yade-mcp (yade-mcp) MCP Server
yade-mcp is an MCP server for YADE, an open-source DEM (discrete-element-method) engine. It provides access to YADE API documentation, supports running simulations, and can manage simulation tasks. The project is associated with topics including AI, Claude/Anthropic, and LLM/MCP integration.
🛠️ Key Features
Browse YADE API docs
Run YADE simulations
Manage tasks related to simulations
🚀 Use Cases
Integrate YADE simulation workflows with MCP-capable clients
Use discrete-element-method tooling for geomechanics and particle simulations
⚡ Developer Benefits
Exposes YADE functionality for automated simulation runs
Fits developer environments using Python, scientific-computing, and MCP
⚠️ Limitations
Only described at a high level (details of available tools and operations are not included in the provided source data)
yade-mcp connects AI agents to YADE, the open-source discrete element method engine, through the Model Context Protocol. The agent browses the YADE API, runs code in a live YADE session, launches long simulations as background tasks, and reads what you type at the YADE console.
Tools (7)
Two documentation tools (no bridge needed) and five execution tools (bridge required):
Tool
Purpose
Bridge
yade_browse_api
Walk the YADE Python class tree
No
yade_query_api
BM25 keyword search across the API
No
yade_execute_code
Run Python in the live YADE process; returns synchronously
Yes
yade_execute_task
Submit a script as a long-running background task
Yes
yade_check_task_status
Inspect a running or finished task (output, status)
Yes
yade_interrupt_task
Stop a running task at an iteration boundary, or cancel a queued one
Yes
yade_list_tasks
List submitted tasks with metadata
Yes
Example Prompts
"Set up a triaxial compression test on a dense packing and plot deviatoric stress against axial strain"
"Build an irregular particle as a level set body and drop it onto a plane"
"The simulation is still running, check the unbalanced force without stopping it"
"Look up how GlobalStiffnessTimeStepper picks the timestep, then add it to this model"
"The command I just typed in the console raised an error, what went wrong?"
"List what was run yesterday and summarize what each task produced"
uv installed. It provides the uvx launcher that agent clients use to run yade-mcp; without it the client reports No such file or directory when starting the server.
An AI agent: Claude Code, Codex CLI, Gemini CLI, or any MCP-capable client
Agentic Setup (Recommended)
Copy this to your AI agent and let it self-configure:
text
Fetch and follow this bootstrap guide end-to-end:
https://raw.githubusercontent.com/yusong652/yade-mcp/master/docs/agentic/yade-mcp-bootstrap.md
Manual Setup
1. Register the MCP server with your agent (use the line for yours):
YADE embeds one specific interpreter (the system python3 for the Debian and Ubuntu packages, or the one it was built against). A conda or venv Python is a different interpreter, and a package installed there is invisible to YADE. The reliable way to hit the right one is to install from inside YADE, where sys.executable is that interpreter. In the YADE console:
No module named pip: the interpreter has no pip. Install it with the system package manager, for example sudo apt install python3-pip.
externally-managed-environment (Debian 12, Ubuntu 23.04 and later): pip refuses --user by default. Add "--break-system-packages" after "--user" in the command above.
Then exit and restart YADE so the new package directory is picked up.
The bridge is proposed for inclusion in YADE itself (yade-dev/trunk !1187). Once it ships with YADE, this step goes away and the bridge starts with from yade import mcpbridge.
3. Start the bridge in the YADE console:
python
import yade_mcp_bridge
yade_mcp_bridge.start()
It prints one line: YADE MCP Bridge on http://localhost:9002, log: <cwd>/.yade-mcp/bridge.log.
Verify
Restart your AI agent and ask it to check that it is connected to YADE. It calls yade_execute_code; ok: true in the response means the whole chain works.
Daily Startup
Once first-time setup is done, each new YADE session only needs the bridge started again. In the YADE console:
python
import yade_mcp_bridge
yade_mcp_bridge.start()
The MCP client config persists.
Configuration
Port
The bridge listens on 9002 by default. To use another port, pass it to start():
python
yade_mcp_bridge.start(port=9008)
The MCP server connects to 9002 unless told otherwise, so register it with the matching URL:
When YADE runs inside a container, bind the bridge to all interfaces so it is reachable from outside:
python
yade_mcp_bridge.start(host="0.0.0.0")
Publish the port when starting the container (for Docker, -p 9002:9002).
Features
Live REPL in the running YADE process: yade_execute_code runs Python in the session's own namespace, so state persists between calls. It keeps working while a task runs, for reading intermediate results without stopping the simulation.
Task lifecycle: submit a script as a background task, tail its output, stop it at an iteration boundary, fix and resubmit. Tasks queue up and run one at a time, so a multi-stage pipeline can be submitted in one go.
Task history across sessions: every task's script, output, and final state stay on record. A new agent session lists what was run and picks up without being told.
Console input reaches the agent: lines you type at the YADE console arrive in the agent's context on its next call, so you can work at the console and with the agent at the same time.
API documentation without a bridge: the class tree and a BM25 search over the YADE Python API work offline, from a corpus refreshed against current YADE releases.
Multi-client: works with Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, OpenCode, toyoura-nagisa, and other MCP clients.