yusong652/yade-mcp

English | 简体中文
O.engines += [LLM()] # yet another engine.
**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"*
First-time Setup
Prerequisites
- **YADE** installed
- **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:
Manual Setup
**1. Register the MCP server** with your agent (use the line for yours):
Or fill in the MCP config file by hand:
**2. Install the bridge into YADE's Python.**
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:
Two things can go wrong here:
- 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.