YADE MCP Server

yade-mcp

English | 简体中文

O.engines += [LLM()] # yet another engine.

yade-mcp 通过 Model Context Protocol，将 AI Agent 连接到 YADE——这是一款开源离散元方法引擎。Agent 可以浏览 YADE API、在实时 YADE 会话中运行代码、以后台任务启动长时间仿真，并读取你在 YADE 控制台中输入的内容。

工具（7 个）

两个文档工具（无需 bridge）和五个执行工具（需要 bridge）：

工具	用途	Bridge
yade_browse_api	遍历 YADE Python 类树	否
yade_query_api	使用 BM25 对 API 进行关键词搜索	否
yade_execute_code	在实时 YADE 进程中运行 Python；同步返回	是
yade_execute_task	将脚本作为长时间运行的后台任务提交	是
yade_check_task_status	检查正在运行或已完成的任务（输出、状态）	是
yade_interrupt_task	在迭代边界停止正在运行的任务，或取消排队中的任务	是
yade_list_tasks	列出已提交的任务及其元数据	是

示例提示词

• “在密实颗粒堆积上设置三轴压缩试验，并绘制偏应力与轴向应变的关系图”
• “将不规则颗粒构建为水平集实体，并使其落到平面上”
• “仿真仍在运行，检查不平衡力，但不要停止仿真”
• “查找 GlobalStiffnessTimeStepper 如何选择时间步，然后将其添加到此模型中”
• “我刚才在控制台输入的命令报错了，出了什么问题？”
• “列出昨天运行的任务，并总结每个任务的产出”

首次设置

前提条件

• 已安装 YADE
• 已安装 uv。它提供 Agent 客户端用于运行 yade-mcp 的 uvx 启动器；如果未安装，客户端启动服务时会报告 No such file or directory。
• AI Agent：Claude Code、Codex CLI、Gemini CLI，或任何支持 MCP 的客户端

Agent 配置（推荐）

将以下内容复制给你的 AI Agent，让它自动完成配置：

Fetch and follow this bootstrap guide end-to-end:
https://raw.githubusercontent.com/yusong652/yade-mcp/master/docs/agentic/yade-mcp-bootstrap.md

手动设置

1. 向你的 Agent 注册 MCP 服务（选择适用于你的那一行）：

# Claude Code
claude mcp add yade-mcp -- uvx yade-mcp

# Codex CLI
codex mcp add yade-mcp -- uvx yade-mcp

# Gemini CLI
gemini mcp add yade-mcp uvx yade-mcp

或者手动填写 MCP 配置文件：

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

2. 将桥接程序安装到 YADE 的 Python 中。

YADE 内嵌了一个特定的解释器（Debian 和 Ubuntu 软件包使用系统的 python3，其他情况则使用构建 YADE 时所用的解释器）。Conda 或 venv 中的 Python 是另一个解释器，在其中安装的软件包对 YADE 不可见。要确保安装到正确的解释器，可靠的做法是在 YADE 内部安装，因为此时 sys.executable 指向的就是该解释器。在 YADE 控制台中：

import sys, subprocess
subprocess.check_call([sys.executable, "-m", "pip", "install", "--user", "yade-mcp-bridge"])

这里可能会遇到两个问题：

• No module named pip：该解释器没有 pip。使用系统软件包管理器安装，例如 sudo apt install python3-pip。
• externally-managed-environment（Debian 12、Ubuntu 23.04 及更高版本）：pip 默认会拒绝使用 --user。在上面的命令中，将 "--break-system-packages" 加在 "--user" 后面。

然后退出并重启 YADE，以便加载新的软件包目录。

目前计划将桥接程序纳入 YADE 本身（yade-dev/trunk !1187）。待其随 YADE 一同发布后，就不再需要这一步，桥接程序将通过 from yade import mcpbridge 启动。

3. 在 YADE 控制台中启动桥接程序：

import yade_mcp_bridge
yade_mcp_bridge.start()

它会打印一行内容：YADE MCP Bridge on http://localhost:9002, log: <cwd>/.yade-mcp/bridge.log。

验证

重启 AI Agent，并让它检查是否已连接到 YADE。它会调用 yade_execute_code；如果响应中的 ok: true，就表示整个链路正常工作。

日常启动

完成首次设置后，每次启动新的 YADE 会话时，只需再次启动桥接程序。在 YADE 控制台中：

import yade_mcp_bridge
yade_mcp_bridge.start()

MCP 客户端配置会保留。

配置

端口

桥接程序默认监听 9002 端口。要使用其他端口，请将其传给 start()：

yade_mcp_bridge.start(port=9008)

除非另有说明，MCP 服务会连接到 9002 端口，因此注册时请使用对应的 URL：

{
  "mcpServers": {
    "yade-mcp": {
      "command": "uvx",
      "args": ["yade-mcp", "--bridge-url", "http://localhost:9008"]
    }
  }
}

容器

在容器内运行 YADE 时，将桥接程序绑定到所有接口，以便从外部访问：

yade_mcp_bridge.start(host="0.0.0.0")

启动容器时发布该端口（对于 Docker，使用 -p 9002:9002）。

功能

• 在运行中的 YADE 进程内使用实时 REPL：yade_execute_code 会在会话自身的命名空间中运行 Python，因此状态会在调用之间保留。任务运行期间也能继续使用，可读取中间结果而无需停止模拟。
• 任务生命周期管理：将脚本作为后台任务提交、查看其输出、在迭代边界处停止任务，修复后重新提交。任务会排队并逐个运行，因此可以一次性提交多阶段流水线。
• 跨会话任务历史：每个任务的脚本、输出和最终状态都会留档。新的 Agent 会话可以查看已运行的任务并接续工作，无需额外告知。
• 控制台输入会传递给 Agent：你在 YADE 控制台中输入的内容会在 Agent 下次调用时进入其上下文，因此你可以同时使用控制台和 Agent。
• 无需桥接程序即可查阅 API 文档：类树以及针对 YADE Python API 的 BM25 搜索均可离线使用，语料会根据当前 YADE 版本更新。
• 多客户端支持：兼容 Claude Code、Codex CLI、Gemini CLI、GitHub Copilot CLI、OpenCode、toy​​oura-nagisa 及其他 MCP 客户端。

故障排除

请参阅引导指南中的故障排除。

贡献

有关开发环境设置和指南，请参阅 CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。