Blender MCP N8n

适用于n8n的Blender MCP服务器

一个模型上下文协议（MCP）服务器，将Blender的3D建模功能暴露给n8n工作流。

系统架构

为了避免混淆，该项目由两个核心部分组成：

1. 搅拌机MCP插件：已安装插件 *里面* 搅拌机。它充当本地执行引擎，接收命令并操纵3D场景。
2. MCP网桥服务器：一个独立的Python服务器(src/)它充当网关。客户喜欢 n8n 连接到此网桥，然后网桥将命令转发到活动的Blender插件。

graph LR
    n8n[n8n / AI Agent] -- "MCP (HTTP Streamable)" --> Bridge[MCP Bridge Server]
    Bridge -- "Local WebSockets" --> Addon[Blender MCP Addon]
    Addon -- "Python API" --> Blender[Blender Engine]

快速开始

1.安装依赖项

pip install -r requirements.txt

配置

创建一个 .env 根目录中的文件以自定义您的设置：

安装

方法1：压缩并安装（推荐）

1. 拉上拉链 blender_mcp_addon 文件夹（放入 blender_mcp_addon.zip).
2. 打开搅拌机。
3. 首选 编辑 > 偏好 > 附加组件.
4. 点击 安装。.. 并选择 .zip 文件。
5. 搜索“Blender MCP”并启用复选框。

方法2：手动复制（开发人员）

1. 复制 blender_mcp_addon 文件夹到Blender插件目录：

- 视窗: %USERPROFILE%\AppData\Roaming\Blender Foundation\Blender\4.x\scripts\addons - macOS: ~/Library/Application Support/Blender/4.x/scripts/addons

1. 重新启动Blender。
2. 在首选项中启用“Blender MCP”。

为什么是文件夹而不是单个文件？

随着插件的增长，一个1800多行的文件变得无法维护。我们已将逻辑划分为功能模块(modeling, materials, anim等），使其专业、可读且更易于扩展。

用法

1.启动搅拌机MCP插件

1. 打开 N面板 （按 N 在3D视口中）。
2. 寻找 搅拌机MCP 选项卡。
3. 点击 启动MCP服务器.

2.启动MCP网桥服务器

# Standard mode
python -m src.main serve

# Recording mode (Save all commands to a file)
python -m src.main serve --record my_session.json --name "Building My House"

服务器将于启动 http://localhost:8008 HTTP Streamable端点位于 /mcp。它使用详细的日志记录来准确显示正在调用哪些工具及其结果。

桥接会话（录制和回放）

这 桥梁会议 该功能允许您记录您或AI的工具调用，并在以后回放。这对于宏、创建版本控制或一致设置复杂场景非常有用。

录制会话

要记录服务器运行时对网桥进行的所有工具调用，请执行以下操作：

python -m src.main serve --record path/to/session.json --name "My Project" --description "Optional description"

n8n或其他客户端进行的任何工具调用都将自动保存到JSON文件中。

重播会话

要播放以前录制的会话，请执行以下操作：

# Default (Stateful - HTTP Streamable) - Recommended for speed
python -m src.main play path/to/session.json

# Stateless mode (Standard HTTP) - Slower due to handshake overhead
python -m src.main play path/to/session.json --transport stateless

\[！提示\] 性能说明：状态模式的播放速度要快得多，因为它保持了持久连接。无状态模式需要完整的MCP握手（初始化/发现） *每* 录音中的单个工具调用，导致明显的开销。

会话格式

会话以JSON文件的形式存储，其中包含元数据（名称、描述、时间戳）和命令对象列表（工具名称、参数和时间戳）。

会话编辑器（视觉检查器）

我们提供了一个内置的静态web编辑器来检查和编辑您的录音：

1. 打开 session_editor/index.html 在您的网络浏览器中。
2. 点击 加载会话 并选择您的 session.json.
3. 你可以：

- 编辑元数据（会话名称、描述）。 - 按工具名称筛选命令。 - 添加和编辑命令：使用带有模式验证的交互式模式来发现工具、安全地修改参数或添加全新的步骤。 - 直接在JSON编辑器卡中编辑工具参数。 - 重新排序或删除不必要的命令。 - 导出JSON 将更改保存到新文件。

3.配置n8n工作流

n8n Design

1. 添加 MCP客户端工具 节点
2. 配置：

- HTTP流式传输端点: http://localhost:8008/mcp - 认证：无 - 要包含的工具：全部

1. 连接到 AI 代理 节点

4.开发：更新和应用更改

如果修改插件代码或MCP服务器逻辑，请执行以下步骤以确保应用更改：

1. 重新加载脚本：在Blender中，按 F3 并输入 “重新加载脚本” （或使用快捷方式 Alt + R 如果已配置）。
2. 重新启动Blender服务器：在N面板中，单击 停止MCP服务器 然后 启动MCP服务器 再一次。
3. 重新启动Python服务器：使用以下命令停止并重新启动服务器 python -m src.main serve.

\[！重要\] 所有Blender操作现在都通过命令队列在主线程上运行，确保稳定性并防止依赖图错误。

可用工具

服务器暴露 70+搅拌机工具 跨越多个类别：

检查

集合

建模

建筑造型

MEP（系统）工程

材料

动画

渲染

相机

照明

历史

n8n中的示例用法

示例交互

用户： 在\[0,0,2\]位置创建一个红色金属球体

助理： 太好了！我在\[0,0,2\]位置成功创建了一个红色金属球体。以下是所做的工作： - 在坐标\[0,0,2\]处创建了一个名为“RedMetallicSphere”的球体，半径为1个单位 - 使用预设为红色底色（#FF0000）的抛光金属应用红色金属材料 球体现在已在Blender场景中准备就绪，具有闪亮的红色金属外观。

用户： 复制红色球体，将其移动到\[5,0,2\]，并将其颜色更改为蓝色

助理： 太好了！我已成功完成所有任务： - 复制红色球体并创建了一个名为“BlueMetallicSphere”的新对象 - 将其移动到位置\[5,0,2\] - 将材料改为蓝色金属，并抛光金属表面 现在，场景中有两个金属球体：\[0,0,2\]处的RedMetallicSphere（红色）和\[5,0,2\]（蓝色）处的BlueMetallicSphere。

用户： 选择原始红色球体和复制品，然后为两者添加细分修改器

助理： 杰出的！我成功地： - 已选择两个球体（红色金属球体和蓝色金属球体） - 为两个具有2级细分的对象添加了细分曲面修改器（SUBSURF） 此修改器将平滑和细化两个球体的几何体，使其外观更加光滑和圆润。

用户： 在\[2,0,0\]处添加一个minor_radius为0.1、major_radius为25的圆环

助理： 太好了！我已成功创建了一个符合您要求规格的圆环： - 姓名： 环面 - 职位： \[2, 0, 0\] - 主要半径： 25（管中心到中心的距离） - 小半径： 0.1（管的厚度） 这产生了一个非常薄、很大的圆环，本质上是一个轮廓很薄的大环。它现在位于Blender场景中，与两个金属球体并排！

社区展示

该项目由其社区提供支持！浏览用户创建的录制会话和文档，了解Blender MCP的可能功能：

• 社区画廊：浏览所有用户提交的项目，并学习如何贡献自己的录音。
• 共管公寓楼：创建具有玻璃立面和阳台的程序性20层建筑的完整指南。
• 布尔展馆：演示布尔运算、统一结构和高级照明/相机设置。

\[！提示\] 分享你的作品你做了什么很酷的东西吗？查看我们的 贡献指南 学习如何录制、清理和与社区分享您的会话！

⚡ 权力提示：避免利率限制

要防止n8n或LLM“请求太多”错误，请执行以下操作 无状态电源工作 规则：

1.避免基于选择的工作流

❌ 慢速（4+圈）： select_by_pattern('Wall_*') → create_material('M_Gray') → assign_material() ✅ 快速（1圈）： create_material(name='M_Gray', pattern='Wall_*')

2.按收藏分组

❌ 不可靠的： 选择单个对象。 ✅ 可靠： create_material(name='M_Glass', collection='Cutters')

3.批量创建

如果你需要10个对象，不要一个接一个地创建它们。使用 create_and_array 或 duplicate_object 随着 count.

配置

在中设置环境变量 .env:

BLENDER_MCP_HOST=127.0.0.1
BLENDER_MCP_PORT=8888
BLENDER_ASSETS_DIR=C:/path/to/your/assets

建筑与技术设计

该项目使用模块化 src/ 确保可维护性的结构：

graph TD
    A[main.py] --> B[server.py]
    B --> C[tools/ package]
    C --> D[modeling.py]
    C --> E[scene.py]
    C --> F[materials.py]
    B --> G[connection.py]
    B --> I[sessions.py]
    G --> H[Blender]

运输模型

尽管MCP规范支持持久的HTTP Streamable会话，但许多客户端（包括n8n）目前在无状态执行模型中运行，执行：

Initialize → Discover Tools → Call Tool → Close

对于每一次互动。

服务器使用官方 HTTP流式传输 MCP SDK 1.8.0+中引入的传输，支持有状态会话和无状态请求。

无状态回退机制

为了确保跨客户端的可靠性，服务器实施了一个强大的回退策略：

1. 协议弹性：如果不存在活动的HTTP Streamable会话，服务器将通过HTTP透明地处理标准JSON-RPC请求。
2. 执行隔离：每个工具调用都是独立处理的，可以防止会话损坏或死锁。
3. 视觉成功指标：工具响应前缀为 ✓ 当成功时。这有助于AI Agent的会话记忆确认任务完成，并避免意外的重复执行循环。
4. 明确国家边界：有意分离持久状态：

- 🧠 对话记忆 → AI代理（n8n简单内存） - 🧩 场景状态 → Blender运行时 - 🚀 MCP服务器 → 无状态执行桥

架构图

n8n AI Agent 
      ↓
MCP Client (HTTP Streamable / JSON-RPC)
      ↓
MCP Server (ASGI)
      ↓
TCP Socket Bridge
      ↓
Blender Addon (Main Thread Queue)
      ↓
Blender Scene (Persistent State)

测试

我们使用集成测试套件来验证Blender工具和布局场景。

# Run the Arch layout test
python tests/run_integration.py run --scenario arch

# Run the standard functional grid test
python tests/run_integration.py run --scenario grid

请参阅 集成测试指南 有关验证和基准测试的完整详细信息。

故障排除

服务器无法启动：安装依赖项 pip install -r requirements.txt

连接失败：确保Blender MCP插件在端口8888上运行。

依赖关系图错误：如果你看到这个，请确保你有最新的 blender_mcp_addon 实现主线程命令队列的包。

工具未出现在n8n中：检查HTTP流式传输端点URL是否正确(http://localhost:8008/mcp)

致谢

这个项目的灵感来自 搅拌机mcp 由\[ahujasid\]撰写，展示了MCP服务器在Blender自动化中的潜力。

许可证

MIT许可证-有关详细信息，请参阅许可证文件