内容
Bonsai MCP
本地 **模型上下文协议** 服务器，连接任意 MCP 客户端（Claude Desktop, Claude Code, Cursor, VS Code, OpenAI Codex）连接到正在运行的 **Blender + Bonsai** （BlenderBIM）会话。检查场景，查询已加载的 IFC 项目，捕获视口，并在 Blender 内运行 Python。
```
MCP 客户端 --stdio--> bonsai-mcp --127.0.0.1:9878--> Blender 插件（bpy + Bonsai + IfcOpenShell）
```
本项目是 [IFC-CoPilot: A Tool-Based Framework for LLM-Driven IFC Building Design](https://show2instruct.github.io/ifc-copilot/) 的一部分，也是 [ifc-bonsai-mcp](https://github.com/Show2Instruct/ifc-bonsai-mcp) 的改进版本。
## 要求
- **Blender 3.6+** （推荐 4.x）。
- **Bonsai (BlenderBIM)**，仅用于 IFC 工具。从 [bonsaibim.org](https://bonsaibim.org) 安装。
- **uv**，一次性安装。运行服务器并为您处理 Python 3.10+。
- **git**，用于克隆此仓库。服务器从您的本地检出运行；它不发布到 PyPI。
## 设置（一次性）
执行这些操作一次。`uv` 在您第一次运行时将所有内容安装到仓库的自己的 `.venv` 中；不会全局安装任何内容，也不会从 PyPI 获取任何内容。
**1. 安装 uv：**
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
**2. 克隆此仓库** 到一个永久位置，并记录其完整路径；您将在下面将 MCP 客户端指向它：
```bash
git clone https://github.com/show2instruct/bonsai-mcp.git
```
## 快速入门
### 1. 安装 Blender 插件
1. 在 Blender 中：**编辑 > 首选项 > 插件**。在 Blender 4.2+/5.x打开 **▾** 菜单（右上角）> **从磁盘安装...**；在旧版本中使用 **安装...** 按钮。
2.克隆的仓库中blender_addon/bonsai_bridge.py`**：确切的文件，而不是 `scripts/package_addon.py` 或 `.zip`。然后勾选 **Bonsai MCP Bridge** 以启用它。
3. 打开侧栏（按 **N**）> **Bonsai MCP** 选项卡 > **启动桥梁**。它现在监听 `127.0.0.1:9878`。
### 2. 连接您的客户端
将您的客户端指向您克隆的文件夹。在下面的每个地方，将 `/path/to/bonsai-mcp` 替换为该路径。在 Windows 中使用 JSON 时，请使用正斜杠或双反斜杠（`C:\\Users\\you\\bonsai-mcp`）。
- ** Code:**
```bash
claude mcp add bonsai-mcp -- uv run --directory /path/to/bonsai-mcp bonsai-mcp
```
- **Claude Desktop, Cursor, VS Code** 和其他客户端：在客户端的 MCP 配置中添加以下内容，然后重启客户端：
```json
{
"mcpServers": {
"bonsai-mcp": {
"command": "uv",
"args": ["run", "--directorypath/to/bonsai-mcp", "bonsai-mcp"]
}
}
}
```
在 Windows 上，如果客户端找不到 `uv`，请使用其完整路径作为 `command`（例如 `C:\\Users\\you\\.local\\bin\\uv.exe`）。
`uv run` 在首次启动时将项目构建到仓库的 `.venv` 中（可编辑，以便您的本地编辑在下一次重启时生效），并在此后缓存它。
### 3. 验证
在 Blender 运行并启动桥梁后，从克隆的文件夹中运行：
```bash
uv run bonsai-mcp doctor
```
`doctor` 会 ping 桥梁并报告 Blender / IfcOpenShell 状态以及它公开的工具。
每个客户端的配置路径、Windows `uv.exe` 路径说明和可选的 `BONSAI_MCP_*` 设置在 [`docs/clients.md`](docs/clients.md) 中。示例配置位于 [`examples/`](./examples) 中；设置 `--directory` 路径到您的克隆。
## 工具
八种工具，每种工具都标记为 `[QUERY]` （只读）或 `[EDIT]` （修改状态）。
| 类别 | 工具 | 目的 |
| -------- | ------------------------- | ----------------------------------------------------------- |
| QUERY | `get_scene_info` | 场景摘要和可选的过滤对象列表。 |
| QUERY | `get_selected_objects` | 当前对象的每个对象信息。 QUERY | `get` | 一个或多个对象的 属性和数量集。 |
| QUERY | `get_viewport_screenshot` | 捕获视口（使用 `view`/`fit` 定位），以及结构化的视口状态。 |
| QUERY | `get_ifc_project_info` | 模式、计数、材料、分类。 |
| EDITexecute_ifc | 运行 IfcOpenShell / Bonsai。`bpy阻止。 |
| EDIT | `execute_blender_code` | 运行具有完全 `bpy` 访问权限的任意 Python 代码。 |
| EDIT | `save_file` | 就、另存为（可选的视口。 |
完整参考资料，包括输入、输出和示例：/tools.md`](docs/tools.md)。
示例提示，在 B 中打开 IFC
> “列出模型中的每个墙及其耐。”
## 安全
桥梁仅绑定到 `127.0.1`，并且验证，并且 `execute_bl` 运行任意 Python 代码。请像对待您机器上的开放 Python REPL 一样对待它，并且永远不要网络。参见 [`docs/safety.md`](docs/safety.md)。
## 文档
- [安装](docs/installation.md)
- [客户端设置](docs/clients.md) （Claude, VS Code, OpenAI）
- [工具参考](docs)
- [安全](docs/safety.md)
- [故障排除](docs/troubleshooting.md)
## 贡献
Python 3.10+ 和 `uv`：
```bash
uv venv
uv pip install -e ".[dev]"
uv run ruff check src tests blender_addon scripts
uv run pytest
```
为行为更改添加测试和文档。通过 [GitHub Security Advisories](https://github.com/show2instruct/bonsai-mcp/security/advisories/new) 私密报告安全问题 许可证
MIT。参见 [LICENSE](LICENSE)。
