blender-lab-mcp-client

一个 MCP 客户端，使用 官方 Blender.org “Blender Lab” MCP 插件的实际线路协议，暴露与 djeada/blender-mcp-server 相同的 27 个工具——但针对的是 blender.org/lab/mcp-server，而不是该项目自带的插件。

为什么有这个项目

（至少）有两个无关的 “Blender + MCP” 项目，恰好共享同一个名称、同一个默认端口和相似的定位：

1. djeada/blender-mcp-server — 提供一对配套实现：它自己的 Blender 插件 以及 一个 Python MCP 客户端，通过 localhost:9876 上的换行符分隔的 {"id", "command", "params"} / {"success", "result"} 协议通信。

2. 官方 Blender Lab 插件（blender.org/lab/mcp-server，维护者为 “Blender Authors”）— 一个完全独立的项目。它也监听 localhost:9876，但只提供 插件 这一侧。它使用空字节分隔的 {"type": "execute", "code": ..., "strict_json": ...} 请求和 {"status": "ok"|"error", "result": ...} 响应，没有内置的具名命令分发器（它只是对 bpy 执行原始 Python），并且在每次请求后都会关闭 TCP 连接。

如果你安装了官方 Blender Lab 插件，却将 MCP 客户端指向 djeada/blender-mcp-server（例如通过 uvx blender-mcp-server），每次工具调用都会失败，错误类似：

Extra data: line 1 column 51 (char 50)

或者，在下一次调用时：

Lost connection to Blender: Blender connection closed

这不是连接不稳定、进程过时或 Blender 的 bug——而是两个互不相关的协议在互相错位。djeada 的客户端发送一个换行符终止的请求，插件始终不识别；插件让客户端超时，回送一个简短的以空字节结尾的错误；而客户端的 readline() 在 JSON 对象之后立即被这个空字节卡住了。

这个包通过生成等价的 bpy Python 代码，并通过 Blender Lab 插件的 实际 协议发送，重新实现了原有的 27 个 MCP 工具，因此工具名称、参数和行为保持不变——只是底层的线路格式变了。

安装

1. 在 Blender 中安装官方 Blender Lab MCP 插件（编辑 → 偏好设置 → 插件 → 搜索 “MCP”，或通过扩展平台），并确认它在 127.0.0.1:9876 上监听（插件偏好设置 → 启动服务器）。

2. 安装这个包：

   git clone https://github.com/A-to-PC/blender-lab-mcp-client.git
   cd blender-lab-mcp-client
   pip install -e .

3. 将你的 MCP 客户端指向它。对于 mcp.json 风格的配置：

   {
     "servers": {
       "Blender": {
         "type": "stdio",
         "command": "blender-lab-mcp-client"
       }
     }
   }

   或者无需安装，直接通过 uv 从源码运行：

   {
     "servers": {
       "Blender": {
         "type": "stdio",
         "command": "uv",
         "args": ["run", "--project", "/absolute/path/to/blender-lab-mcp-client", "blender-lab-mcp-client"]
       }
     }
   }

工具参考

与上游相同的 27 个工具——完整表格请参见 djeada/blender-mcp-server 的工具参考（场景检查、物体操作、材质、渲染/导出、历史、Python 执行、异步任务）。名称和参数保持不变；只是底层传输方式不同。

已知限制

• blender_python_exec_async / blender_job_status / blender_job_cancel / blender_job_list（仅 bridge 传输）被伪装成同步执行。 插件真正的延迟任务机制要求被执行的代码本身设置一个 check_is_finished 可调用对象，而这无法从任意提交的代码中通用地合成出来。针对 正在运行中的 Blender 会话的异步调用实际上会同步运行，并立即报告为 "succeeded"。对于真正长时间运行的工作（物理烘焙、重型模拟），请改用 transport="headless"——该路径会运行一个独立的 blender -b 后台进程，不受此限制影响。

• 每个请求一个连接。 插件在每次响应后都会关闭其 socket，因此这个客户端无法复用持久连接——每次工具调用都会打开一个新的 TCP 连接。这与插件的实际设计相符；这不是一个可以在客户端“修复”的性能捷径。

• 已针对 Blender 5.2 LTS 和 Blender Lab 插件进行测试。物体/材质辅助代码使用标准的 bpy.ops.* 调用，应该能在任何近期 Blender 版本上工作，但尚未在版本矩阵中验证。

致谢

从 djeada/blender-mcp-server（MIT 许可）fork 而来，原作者 Adam Djellouli——MCP 工具接口（名称、参数、描述）和 headless.py 后台执行传输层被原样保留。只有 server.py 中的 BlenderConnection 和命令到 bpy 代码的转换层是新的，以针对官方 Blender Lab 插件的协议，而非上游自带的插件。

许可证

MIT —— 参见 LICENSE。