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 APIbpy在当前 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 → 端口配置」的顺序排查即可。