Blender MCP 工作原理解析：Socket 架构、JSON 通信协议与端口配置-开发者社区

Blender MCP 工作原理解析：Socket 架构、JSON 通信协议与端口配置

Blender MCP 是怎么工作的？两组件架构、TCP Socket 通信流程、JSON 协议格式与常见连接问题排查

关键词

Blender MCP、Blender MCP 工作原理、MCP Server、bpy、localhost 9876、BLENDER_PORT、execute_blender_code

摘要

大家好这里是「代码简单说」，这篇文章主要分享一下 Blender MCP 的工作原理。MCP for Blender 由 Blender 插件和 Python MCP Server 两个组件构成，两者通过 TCP Socket 上的 JSON 协议通信。理解这套架构，能帮你快速定位「连接失败」「工具没响应」「执行超时」这类问题。适合正在使用或准备接入 Blender MCP 的开发者阅读。

一、Blender MCP 是什么，为什么要理解它的架构

MCP for Blender 的作用是把 AI 客户端（Claude Desktop、Cursor 这类支持 MCP 的工具）和 Blender 连起来，让 AI 直接操作 Blender 场景。它由两个互相配合的组件组成：

Blender 插件（Addon）：运行在 Blender 内部，本质上是一个监听localhost:9876的 Socket 服务。它接收 JSON 命令，然后用 Blender Python API（bpy）在当前 Blender 实例里直接执行。
MCP Server：一个独立的 Python 进程，实现了 Model Context Protocol（官方配置示例中通过uvx blender-mcp启动）。它一头连接 Blender 插件，一头把 Blender 的各种能力以工具（Tool）的形式暴露给 AI 客户端。

为什么要花时间理解这套结构？因为日常遇到的「AI 说连接不上」「工具列表为空」等问题，基本都能对应到这两段链路上的某一环。知道请求怎么流动，排查就有方向。

二、一次请求的完整通信流程

当你在 AI 客户端里发一句「帮我创建一个立方体」，请求按下面的顺序流动：

AI 客户端调用 MCP Server 上的某个工具。
MCP Server 把命令封装成 JSON，通过 TCP 发给 Blender 插件。
插件在正在运行的 Blender 实例里执行对应的bpy代码。
插件把执行结果返回给 MCP Server。
MCP Server 再把结果转回 AI 客户端。

整个过程实时完成，前提是 Blender 以带界面的方式（GUI）运行着。

三、通信协议：JSON over TCP

命令和响应都是 JSON 对象，通过 TCP Socket 交换。

一条命令包含type和params两个字段，以读取场景信息为例：

{"type":"get_scene_info","params":{}}

响应包含status字段，以及result或message：

{"status":"success","result":{}}

两个和协议直接相关的配置点：

默认地址是localhost:9876。如果端口被占用或有其他需求，可以通过环境变量BLENDER_HOST和BLENDER_PORT修改。
所有操作默认 180 秒超时。跑大任务（批量建模、复杂脚本）时，把任务拆成多个小步骤，避免单次调用超时。

四、两类工具：高层封装和底层代码执行

MCP for Blender 暴露给 AI 的工具分两类：

高层工具：比如get_scene_info（读场景信息）、get_object_info（查对象详情）、get_viewport_screenshot（截取视口）、download_polyhaven_asset（下载 Poly Haven 资源）。这类工具发送结构化命令，插件执行预定义的bpy逻辑，返回干净的结果。
底层代码执行：execute_blender_code直接把原始 Python 代码发给 Blender 执行。灵活性没有上限，但代价是对 Blender 环境拥有完全访问权限，包括文件系统。

使用建议：能用高层工具就用高层工具，execute_blender_code留给内置工具覆盖不到的操作。

五、安全模型与使用限制

这部分和日常使用直接相关：

execute_blender_code会在 Blender 里执行任意 Python，执行前先保存工程文件。
插件只监听localhost，默认外部机器访问不到。不要把 9876 端口暴露到公网，也不要在不可信的网络环境里运行。
同一时刻只应该有一个 MCP Server 实例连接 Blender。同时让 Cursor 和 Claude Desktop 连接同一个 Blender 会话，会产生冲突。

六、常见问题

1. AI 客户端一直提示连接失败怎么办？

按链路逐段排查：Blender 是否以 GUI 方式启动并加载了插件 → MCP Server 进程是否正常启动 → 插件监听的地址端口和 MCP Server 连接的地址端口是否一致（默认都是localhost:9876）。

2. 端口 9876 被占用怎么办？

通过环境变量BLENDER_HOST和BLENDER_PORT改成其他端口，注意插件侧和 MCP Server 侧的配置要保持一致。

3. 任务执行到一半超时了？

单次操作 180 秒超时是硬性限制。把大任务拆成小步骤，分多次调用。

4. 可以同时用两个 AI 客户端操作同一个 Blender 吗？

不可以。同一时间只允许一个 MCP Server 实例连接，多客户端并发连接同一个 Blender 会话会冲突。

七、总结

MCP for Blender = Blender 内的 Socket 插件 + 外部 Python MCP Server，两者用 JSON over TCP 通信，默认地址localhost:9876，单次操作 180 秒超时。理解这条链路之后，连接类问题基本都能自己定位。完整架构说明见官方文档 https://mcp-for-blender.com 。

以上就是 Blender MCP 工作原理的全部内容，遇到连接问题时按照「插件 → MCP Server → 端口配置」的顺序排查即可。