Bonsai-mcp - 通过 IfcOpenShell 集成 Blender 模型上下文协议，支持 IFC

Bonsai-mcp 是 BlenderMCP 的一个分支，它通过 Bonsai 扩展了原始功能，专门支持 IFC（工业基础类）模型。此集成是一个快速的概念验证，旨在展示将 Claude 或任何 LLM（尽管仅使用 Claude Desktop Client 进行了测试）连接到 Blender 以执行 IfcOpenShell 命令的功能。

特性

• IFC 特定功能：查询 IFC 模型、分析空间结构以及检查建筑元素
• 五个强大的 IFC 工具：检查项目信息、列出实体、检查属性、探索空间结构以及分析关系
• 顺序思考：包含来自 modelcontextprotocol/servers 的顺序思考工具，用于结构化问题解决
• 执行代码工具（来自原始 BlenderMCP 实现）：在 Blender 中创建和修改对象、应用材质以及执行 Python 代码
• 使用标准模型进行测试：已验证可与默认的 ifcopenshell 房屋模型 (AC20-FZK-Haus.ifc) 一起使用

组件

该系统由两个主要组件组成：

1. Blender 插件 (addon.py)：一个 Blender 插件，在 Blender 中创建一个套接字服务器，以接收和执行命令，包括 IFC 特定操作
2. MCP 服务器 (blender_mcp_tools.py)：一个 Python 服务器，实现模型上下文协议并连接到 Blender 插件

安装

前提条件

• Blender 3.0 或更高版本
• Python 3.10 或更高版本
• uv 包管理器
• Bonsai BIM Blender 插件（用于 IFC 功能）

安装 uv：

Mac：

brew install uv

Windows：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex" 
set Path=C:\Users\[username]\.local\bin;%Path%

对于其他平台，请参阅 uv 安装指南。

克隆存储库

git clone https://github.com/JotaDeRodriguez/Bonsai_mcp

Claude for Desktop 集成

编辑您的 claude_desktop_config.json 文件（Claude > 设置 > 开发者 > 编辑配置）以包含：

{
    "mcpServers": {
        "Bonsai-mcp": {
            "command": "uv",
            "args": [
              "--directory",
              "\\your\\path\\to\\Bonsai_mcp",
              "run",
              "tools.py"
          ]
        }
    }
}

安装 Blender 插件

1. 从此存储库下载 addon.py 文件
2. 打开 Blender
3. 转到编辑 > 偏好设置 > 插件
4. 单击“安装...”并选择 addon.py 文件
5. 通过选中“界面：Blender MCP - IFC”旁边的框来启用插件

用法

启动连接

1. 在 Blender 中，转到 3D 视图侧边栏（如果不可见，请按 N）
2. 找到“Blender MCP - IFC”选项卡
3. 单击“连接到 Claude”
4. 确保 MCP 服务器正在运行

与 Claude 一起使用

连接后，您将在 Claude 的界面中看到一个带有锤子图标，其中包含用于 Blender MCP IFC 集成的工具。

IFC 工具

此分支添加了五个强大的 IFC 特定工具：

1. get_ifc_project_info

获取有关 IFC 项目的基本信息，包括名称、描述和不同实体类型的计数。

示例：“这个 IFC 项目的基本信息是什么？”

2. list_ifc_entities

列出特定类型的 IFC 实体（墙、门、空间等）。

示例：“列出此 IFC 模型中的所有墙”或“向我展示此建筑物中的窗户”

3. get_ifc_properties

通过其 GlobalId 获取特定 IFC 实体的所有属性。

示例：“ID 为 1Dvrgv7Tf5IfTEapMkwDQY 的墙的属性是什么？”

4. get_ifc_spatial_structure

获取 IFC 模型的空间层次结构（场地、建筑物、楼层、空间）。

示例：“向我展示此建筑物的空间结构”

5. get_ifc_relationships

获取特定 IFC 实体的所有关系。

示例：“入口门的关系是什么？”

执行 Blender 代码

来自原始 MCP 实现的旧版功能。允许 Claude 在 Blender 中执行任意 Python 代码。谨慎使用。

顺序思考工具

此集成还包括顺序思考工具，该工具可促进详细的、逐步的思考过程，以进行问题解决和分析。

工具参数：

• thought (string)：当前的思考步骤
• nextThoughtNeeded (boolean)：是否需要另一个思考步骤
• thoughtNumber (integer)：当前的思考编号
• totalThoughts (integer)：估计需要的总思考次数
• isRevision (boolean, optional)：这是否修改了之前的思考
• revisesThought (integer, optional)：正在重新考虑哪个思考
• branchFromThought (integer, optional)：分支点思考编号
• branchId (string, optional)：分支标识符
• needsMoreThoughts (boolean, optional)：是否需要更多思考

示例：“使用顺序思考来分析这座建筑的能源效率”

示例命令

以下是一些您可以要求 Claude 使用 IFC 模型执行的操作示例：

• “分析此 IFC 模型，并告诉我它有多少墙、门和窗户”
• “向我展示此建筑物模型的空间结构”
• “列出此 IFC 模型中的所有空间及其属性”
• “识别此建筑物中的所有结构元素”
• “这堵墙与其他元素之间的关系是什么？”
• “使用顺序思考，根据 IFC 模型为此建筑物创建一个维护计划”

故障排除

• 连接问题：确保 Blender 插件服务器正在运行，并且 MCP 服务器已在 Claude 中配置
• IFC 模型未加载：验证您是否已安装 Bonsai BIM 插件，并且已加载 IFC 文件
• 超时错误：尝试简化您的请求或将其分解为更小的步骤

技术细节

IFC 集成使用 Bonsai BIM 模块来访问 Blender 中的 ifcopenshell 功能。通信遵循与原始 BlenderMCP 相同的基于 JSON 的协议，通过 TCP 套接字进行。

限制和安全注意事项

• 原始项目中的 execute_blender_code 工具仍然可用，允许在 Blender 中运行任意 Python 代码。谨慎使用并始终保存您的工作。
• 复杂的 IFC 模型可能需要将操作分解为更小的步骤。
• IFC 查询性能取决于模型大小和复杂性。

鸣谢

• 原始 BlenderMCP 由 Siddharth Ahuja 开发
• 顺序思考工具来自 modelcontextprotocol/servers
• IFC 集成建立在 Bonsai BIM Blender 插件之上

TODO

光标实现 添加 'get_selected_ifc_elements' 描述