盆栽_mcp

Name: 盆栽_mcp
Author: JotaDeRodriguez

作者：JotaDeRodriguez31 星标更新：2025-10-30

安装使用来源：spider==github.com

项目介绍

Bonsai-mcp - 通过IfcOpenShell和Blender集成模型上下文协议（MCP）到IFC

Bonsai-mcp 是 BlenderMCP 的一个分支，它扩展了原始功能，通过 Bonsai 提供对 IFC（工业基础类）模型的专用支持。这种集成提供了一个平台，让大型语言模型（LLMs）能够读取和修改 IFC 文件。

功能

特定于IFC的功能：查询 IFC 模型，分析空间结构，检查建筑元素并提取数量
包含十一项IFC工具：检查项目信息，列出实体，检查属性，探索空间结构，分析关系等
顺序思维：包括来自 modelcontextprotocol/servers 的顺序思维工具，用于结构化问题解决
执行代码工具：从原始的 BlenderMCP 实现中继承，创建和修改对象，应用材质，并在 Blender 中执行 Python 代码

组件

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

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

安装 - 通过MCP客户端设置

先决条件

Blender 4.0 或更新版本
Python 3.12 或更新版本
uv 包管理器
Blender 的 Bonsai BIM 插件（用于 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"
            ]
        }
    }
}

通过 Docker 安装

该仓库附带一个 Dockerfile，使得在不同环境中部署变得简单且一致。

快速开始

# 克隆仓库
git clone https://github.com/JotaDeRodriguez/Bonsai_mcp
cd Bonsai_mcp

# 构建 Docker 镜像
docker build -t bonsai_mcp .

# 运行容器
docker run -p 8000:8000 --name bonsai_mcp bonsai_mcp

运行后，容器将在 http://localhost:8000 上公开 MCP 工具作为 REST/OpenAPI API。

要验证安装，请打开浏览器并导航至
http://localhost:8000/docs
你会看到包含所有可用端点的 Swagger UI
点击某个端点进行测试，然后点击“尝试一下”和“执行”

连接到 Open WebUI 或其他 API 客户端

要将此 API 连接到 Open WebUI：

在 Open WebUI 中，转到设置 > 管理工具服务器
添加一个新的连接：
- URL：http://localhost:8000
- OpenAPI 规范路径：/openapi.json
- 认证：无（除非另有配置）

环境变量

Docker 容器接受多个环境变量来自定义其行为：

# 示例带有自定义设置
docker run -p 8000:8000 \
  -e BLENDER_HOST=host.docker.internal \
  -e BLENDER_PORT=9876 \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  --name bonsai_mcp bonsai_mcp

安装 Blender 插件

从此仓库下载 addon.py 文件
打开 Blender
转到编辑 > 偏好设置 > 插件
点击“安装...”并选择 addon.py 文件
通过勾选旁边的复选框启用插件：“界面：Blender MCP - IFC”

使用

启动连接

在 Blender 中，转到 3D 视图侧边栏（如果不可见，请按 N 键）
查找“Blender MCP - IFC”标签
点击“连接到 Claude”
确保 MCP 服务器正在运行

与 Claude 结合使用

一旦连接，你将在 Claude 的界面中看到一个锤子图标，其中包含 Blender MCP IFC 集成的工具。

IFC 工具

此仓库包括多个 IFC 特定工具，使全面查询和操作 IFC 模型成为可能：

get_ifc_project_info：检索关于 IFC 项目的基本信息，包括名称、描述以及不同实体类型的计数。示例：“这个 IFC 项目的基本信息是什么？”

list_ifc_entities：列出特定类型的 IFC 实体（墙、门、空间等），并可选择限制结果和根据选择过滤。示例：“列出此 IFC 模型中的所有墙”或“显示这栋楼中的窗户”

get_ifc_properties：根据 GlobalId 或当前选定的对象检索特定 IFC 实体的所有属性。示例：“具有 ID 1Dvrgv7Tf5IfTEapMkwDQY 的这堵墙的属性是什么？”

get_ifc_spatial_structure：获取 IFC 模型的空间层次结构（场地、建筑物、楼层、空间）。示例：“显示这栋楼的空间结构”

get_ifc_relationships：检索特定 IFC 实体的所有关系。示例：“入口门的关系是什么？”

get_selected_ifc_entities：获取与当前在 Blender UI 中选定的对象对应的 IFC 实体的信息。示例：“告诉我我在 Blender 中选择了哪些元素”

get_user_view：捕获当前 Blender 视口的图像，允许从用户视角可视化模型。示例：“显示用户当前在 Blender 中看到的内容”

export_ifc_data：将 IFC 数据导出到结构化的 JSON 或 CSV 文件中，可以选择按实体类型或建筑级别过滤。示例：“将所有墙数据导出到 CSV 文件”

place_ifc_object：在指定坐标处创建并定位 IFC 元素，可选旋转。示例：“在坐标 X:10, Y:5, Z:0 处放置一扇门，旋转 90 度”

get_ifc_quantities：计算并获取 IFC 元素的数量（m2, m3 等），可以选择按实体类型或选定的元素过滤。示例：“使用 get_ifc_quantities 工具给我这栋楼中所有墙的面积”

get_ifc_total_structure：检索 IFC 模型的完整层次结构，包括空间元素（项目、场地、建筑物、楼层）以及每个空间容器内的所有建筑元素。这种综合视图结合了空间层次结构与建筑元素，对于生成完整的报告和预算至关重要。示例：“显示此 IFC 模型的完整结构，包括按楼层组织的所有建筑元素”

export_drawing_png：以高分辨率 PNG 图像导出 2D 和 3D 绘图，具有可定制的分辨率和视图参数。从上方指定高度偏移创建正交平面图。示例：“以 1920x1080 分辨率生成地面层的平面图 PNG”

get_ifc_georeferencing_info：从 IFC 文件中检索全面的地理参考信息，包括坐标参考系统（CRS）、地图转换、世界坐标系统、真北方向和场地地理坐标。示例：“此 IFC 模型中有何地理参考信息？”

georeference_ifc_model：在 IFC 模型中创建或更新地理参考信息，允许使用 EPSG 代码或自定义 CRS 定义设置坐标参考系统，建立地图转换使用东经/北纬坐标，并配置场地地理位置。示例：“使用 EPSG:4326 并在纬度 40.7589、经度 -73.9851 处的地理参考此 IFC 模型”

export_bc3_budget：基于加载在 Blender 中的 IFC 模型导出 BC3 预算文件（FIEBDC-3/2016 格式）。此工具通过提取 IFC 空间结构，按类型和类别（结构、砌体、楼板、木工、安装、家具）分组建筑元素，从综合数据库分配单位价格并生成详细测量来创建完整的施工预算。支持多语言输出（西班牙语/英语），并正确编码国际字符。BC3 格式是西班牙施工预算和成本估算的标准。示例：“为此建筑模型生成一份西班牙语的 BC3 预算文件”

功能

自动元素分类：建筑元素被自动分类为类别：
- ESTR：结构元素（梁、柱、基础、桩、坡道、楼梯）
- ALB：砌体（墙）
- FORG：楼板和屋顶
- CARP：木工（门、窗）
- INST：安装（管道、配件、终端、栏杆）
- MOB：家具
准确测量：
- 墙壁按净侧面积测量（考虑开口如门和窗）
- 楼板和屋顶按总体积测量
- 梁、柱和桩按长度（米）测量
- 门、窗和家具按单位计数
多语言支持：生成预算时支持西班牙语或英语，并正确编码（windows-1252）
层次结构：预算章节遵循 IFC 空间层次结构（项目 → 场地 → 建筑 → 层）
单位价格数据库：包括常见建筑元素的综合单位价格，完全可通过 JSON 文件自定义
排序测量：每个类别内的元素按字母顺序排序，便于审查

配置文件

BC3 导出使用位于 resources/bc3_helper_files/ 的外部 JSON 配置文件：

precios_unitarios.json / unit_prices.json：每种 IFC 元素类型的单位价格
spatial_labels_es.json / spatial_labels_en.json：空间元素翻译
element_categories.json：IFC 类型到预算类别的映射

这些文件可以自定义以适应特定项目需求或区域定价标准。

输出

BC3 文件导出到 exports/ 文件夹，符合 FIEBDC-3/2016 格式，包括：

完整的层次章节结构
每个元素的详细测量
单位价格和总计
符合西班牙施工预算标准 bc3 的全部要求

MCP 资源

此集成提供了通过 MCP 资源访问结构化文档的途径：

file://table_of_contents.md：包含生成全面建筑报告的技术报告结构模板。此资源提供了一个标准化的目录，可用于从 IFC 模型创建技术文档时的参考。

MCP 提示

服务器包括专门的 MCP 提示，用于自动化报告生成：

Technical_building_report：基于加载在 Blender 中的 IFC 模型生成全面的技术建筑报告。此提示提供了一个结构化的流程，用于创建多种语言（英语、西班牙语、法语、德语、意大利语、葡萄牙语）的专业建筑文档。提示引导通过系统性地从 IFC 模型中提取数据（包括空间结构、数量、材料和建筑系统），最终生成包含图纸和 3D 可视化的完整技术报告。

执行 Blender 代码

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

顺序思维工具

此集成包括顺序思维工具，用于结构化的问题解决和分析。它促进了一个逐步思考过程，可以分支、修订和适应理解的加深——非常适合复杂的 IFC 模型分析或规划任务。

示例：“使用顺序思维分析基于 IFC 模型的这栋楼的能源效率”

示例命令

这里有一些你可以要求 Claude 对 IFC 模型执行的操作示例：

“分析这个 IFC 模型并告诉我它有多少墙、门和窗户”
“显示这个建筑模型的空间结构”
“列出此 IFC 模型中的所有空间及其属性”
“识别这栋楼中的所有结构元素”
“这堵墙与其他元素之间的关系是什么？”
“生成从 Blender 中打开的 IFC 模型的测量报告”
“使用顺序思维为基于 IFC 模型的这栋楼创建维护计划”
“为当前 IFC 模型生成一份西班牙语的 BC3 预算文件”
“将施工成本估算导出为 BC3 格式，带有英文描述”

故障排除

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

Docker：

“连接被拒绝”错误：确保 Blender 正在运行且插件已启用，并且服务器已启动
CORS 问题：API 默认为所有来源启用了 CORS。如果遇到问题，请检查客户端的 CORS 设置
性能问题：对于大型 IFC 模型，API 响应可能会较慢。考虑调整客户端中的超时设置

技术细节

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

限制及安全注意事项

来自原始项目的 execute_blender_code 工具仍然可用，允许在 Blender 中运行任意 Python 代码。谨慎使用并始终保存工作。
复杂的 IFC 模型可能需要将操作分解为更小的步骤。
IFC 查询性能取决于模型大小和复杂性。
获取用户视图工具返回的是 base64 编码的图像。请确保客户端支持它。

贡献

此 MIT 许可的仓库可以被 fork、修改和以任何方式使用。我欢迎想法和合作，所以不要犹豫联系我进行贡献。

致谢

原始 BlenderMCP 由 Siddharth Ahuja
顺序思维工具来自 modelcontextprotocol/servers
IFC 集成基于 Blender 的 Bonsai BIM 插件

待办事项

与更多 MCP 客户端的集成和测试