yade-mcp

<!-- mcp-name: io.github.yusong652/yade-mcp -->

<p align="center"> <img src="https://raw.githubusercontent.com/yusong652/yade-mcp/assets/assets/header.gif" alt="yade-mcp header" width="720"> </p>

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. Browse API docs, run simulations, and execute code, all through natural conversation.

Tools (7)

2 documentation tools — browse and search the YADE Python API with BM25 keyword search. No bridge required.

5 execution tools — synchronous REPL, async task submission, progress monitoring, interruption, and task history. Requires bridge.

Quick Start

Prerequisites

• YADE installed
• uv installed (for uvx)

Agentic Setup (Recommended)

Copy this to your AI agent and let it self-configure:

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 in your client config:

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

2. Start the bridge inside YADE:

pip install yade-mcp-bridge

Then in a YADE Python console:

import yade_mcp_bridge
yade_mcp_bridge.start()

Verify

Restart your AI agent (Claude Code, Codex CLI, Gemini CLI, etc.) and ask it to call yade_execute_code to verify the connection.

Features

• Rich class documentation — covers the YADE Python API, enriched with real types, defaults, and docstrings
• Hierarchical API browsing — agents navigate categories, subcategories, and classes with progressive disclosure, reducing hallucination
• BM25 keyword search — fast, ranked search across all API docs by natural language queries
• Synchronous REPL — rapid iteration for querying simulation state (O.bodies, O.iter, quick tests)
• Async task lifecycle — submit long-running simulations, monitor progress, gracefully interrupt via PyRunner, and browse history
• Multi-client compatible — works with Claude Code, Codex CLI, Gemini CLI, OpenCode, and other MCP clients

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT — see LICENSE.