Blender MCP 安装配置与 AI 建模实战教程

Blender MCP 把 Blender 变成大模型 Agent 可以直接操控的"手"：AI 通过 execute_code 等工具在你的 Blender 里执行 Python 脚本，实时建模型、调材质、设灯光、加动画。本教程分为两大阶段：第一阶段完成 Blender MCP 插件安装与 ZCode 的 MCP 配置，并排查国内网络与首次启动超时等常见问题；第二阶段以"从零建一座可演示的雷达站"为完整案例，展示从自然语言需求到成品的全流程，最后把成果打包成双击即可运行的演示程序。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

• MCP概念详解与应用完整教程，理解 MCP 协议、stdio 传输与工具调用的基本概念，本教程的所有操作都建立在这套机制之上。

资源下载

• Blender 官网下载地址，本教程使用 Blender 5.2 LTS。
• blender-mcp 项目主页（GitHub），MCP 服务器与 Blender 插件的源码仓库。
• Python环境管理详解与UV的安装与使用教程，用于安装 uvx（MCP 服务器的运行环境），同时系统讲解 uv 与 venv、Conda 的对比与选型。

• 示例脚本打包下载（夸克网盘），包含本教程的 MCP 直驱脚本 mcp_driver.py、雷达站建模脚本与演示启动器源码。下载解压后你将得到如下结构：

  RadarStationMCP/
  ├── mcp_driver.py          # MCP stdio 直驱客户端
  ├── build_radar.py         # 雷达站第一版建模脚本
  ├── recovery_radome.py     # 断电恢复用的全量重放脚本
  ├── add_facilities.py      # 配套设施建模脚本
  ├── demo_autoplay.py       # 演示包自动导览脚本
  ├── launcher.cs            # 演示启动器 C# 源码
  └── assets/                # 教程配图
  

1. Blender MCP 是什么

1.1 三层架构：Agent、MCP 服务器与 Blender 插件

Blender MCP（开源项目 ahujasid/blender-mcp）由两部分组成：一个遵循 MCP 协议的服务器进程，和一个安装在 Blender 内部的插件。服务器本身不懂建模，它只负责把 Agent 发来的命令转发给 Blender；真正干活的是插件——它接收命令后，在 Blender 主线程里执行 Python 代码，再把结果原路返回。

这带来两个重要推论。第一，Blender 必须处于运行状态、且插件内的 socket 服务已启动（监听 127.0.0.1:9876），否则 Agent 调用任何工具都会报"连接失败"。第二，MCP 服务器与 Blender 之间是解耦的：Blender 崩溃重启后，只要重新点击插件里的连接按钮，Agent 侧不需要任何改动。

1.2 提供了哪些工具

其中 execute_blender_code 是主力：它把整段 Python 脚本送进 Blender 的 bpy 环境执行，理论上人能在 Blender 里做的事，AI 都能通过它完成。

1.3 与其他 MCP 服务器的区别

常见的 MCP 服务器（文件系统、数据库、搜索等）是无界面的后台服务，启动即可用。Blender MCP 则依赖一个有界面的图形宿主：插件的 socket 服务跑在 Blender 主线程的定时器里，Blender 一旦关闭服务就消失。因此它的使用流程固定为"先开 Blender 并启动服务，再让 Agent 连接"，这一点在排障时非常重要。

2. 环境准备

2.1 安装 Blender 与 uv

从 Blender 官网下载并安装 Blender 5.2 LTS（或其他 4.x 以上版本），确认 blender.exe 可以正常启动。随后按照 uv 官方文档安装 uv，安装完成后在终端验证：

uvx --version

uvx 是 uv 附带的临时运行器，它会按需把 blender-mcp 包及其依赖安装到独立缓存目录再运行，不需要污染系统 Python 环境。国内网络环境下建议先为 uv 配置镜像源（后文配置文件中会体现）。

2.2 确认 ZCode 配置文件位置

ZCode 的 MCP 服务器配置位于用户配置文件 C:\Users\<你的用户名>\.zcode\cli\config.json 的 mcp.servers 字段下。如果该文件中已有其他 MCP 服务器（如 chrome-devtools、github），直接在 mcp.servers 对象里追加即可；MCP 配置的整体结构见 MCP概念详解与应用完整教程。

3. 安装 Blender MCP 插件与配置 ZCode

3.1 安装 Blender 端插件

blender-mcp 的服务器包里自带了插件文件，最简单的安装方式是一条命令：

uvx blender-mcp install-addon

它会自动发现 Blender 的插件目录（Windows 下为 %APPDATA%\Blender Foundation\Blender\5.2\scripts\addons\），把插件复制为 blender_mcp.py。

如果与 GitHub 的直连不稳定，也可以手动下载插件文件后复制到上述目录。实战中有一个可直接复制的经验：当 raw.githubusercontent.com 被重置、git clone 又被失效的系统代理拦截时，api.github.com 通常仍可直连，用它取原始文件并通过 git blob SHA 校验完整性：

curl --noproxy "*" -sSL -H "Accept: application/vnd.github.raw" -o blender_mcp_addon.py "https://api.github.com/repos/ahujasid/blender-mcp/contents/addon.py?ref=main"

3.2 在 ZCode 中注册 MCP 服务器

编辑 config.json，在 mcp.servers 下新增 blender-mcp 节点：

{
  "mcp": {
    "servers": {
      "blender-mcp": {
        "type": "stdio",
        "command": "C:/Users/<你的用户名>/.local/bin/uvx.exe",
        "args": ["blender-mcp"],
        "env": {
          "UV_DEFAULT_INDEX": "https://pypi.tuna.tsinghua.edu.cn/simple",
          "UV_INDEX_URL": "https://pypi.tuna.tsinghua.edu.cn/simple"
        },
        "timeoutMs": 60000
      }
    }
  }
}

三个细节值得注意。第一，env 中的清华镜像配置是特意加入的：uv 会读取这两个环境变量，首次运行时从镜像站下载 blender-mcp 的全部依赖，速度远快于默认源。第二，timeoutMs 建议设置为 60000：ZCode 默认的 MCP 连接超时是 30 秒，而 uvx 首次运行需要下载约 31 个依赖包，实测在国内网络下经常超过 30 秒，导致服务器被判定为启动失败、工具不会注册——这是本教程实测中踩到的第一个坑。第三，command 写 uvx.exe 的绝对路径，避免 PATH 差异导致的启动失败。

3.3 预热依赖包

在注册之前（或修改配置后），手动执行一次以下命令，把依赖包预先下载到 uv 缓存：

uvx --from blender-mcp python -c "import blender_mcp, blender_mcp.server"

看到正常退出无报错即可。此后 uvx blender-mcp 将在秒级完成启动，从根本上规避超时问题。

3.4 启动 Blender 端服务并验证

打开 Blender，在 3D 视口按 N 调出侧边栏，找到 MCP for Blender 标签，点击 Connect to MCP Server，状态显示已连接即表示 Blender 端就绪（监听 127.0.0.1:9876）。可以用以下命令确认端口状态：

netstat -ano | findstr 9876

最后验证整条链路：重启 ZCode 会话（MCP 工具只在会话启动时注册），新会话中就能看到 mcp__blender-mcp__get_scene_info 等工具。调用 get_scene_info，返回类似 BlenderMCP v1.30.0 的场景信息即表示全链路打通。

3.5 常见故障排查

4. 实战：让 AI 建一座可演示的雷达站

4.1 AI 建模的工作方式

让 AI 通过 MCP 建模，本质是一个"下达需求、执行代码、验证效果、迭代修复"的循环：你用自然语言描述需求，Agent 把它翻译成 bpy 代码，通过 execute_blender_code 送入 Blender 执行，然后用渲染或视口截图检查结果，发现偏差就再发一版修正代码。整个过程你不需要碰 Blender 界面，但随时可以介入调整。

4.2 驱动 MCP 的两种形态

形态一：Agent 工具直调。 在 ZCode 会话中直接说"用 MCP 在 Blender 里建一个立方体"，Agent 会自动调用 mcp__blender-mcp__execute_blender_code 工具。这是最自然的方式，适合交互式迭代。

形态二：脚本直驱 MCP 服务器。 MCP 服务器本质是一个读 stdin、写 stdout 的 JSON-RPC 进程，任何语言都能驱动它。编写一个约 80 行的客户端（完整脚本见资源下载的 mcp_driver.py），核心流程为：启动 uvx blender-mcp 子进程、发送 initialize 握手、注册通知，然后调用工具：

resp = client.request("initialize", {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {"name": "demo", "version": "1.0"},
})
client.notify("notifications/initialized")
out = client.call("execute_blender_code", {"code": bpy_script})

这种形态适合把建模过程固化成可重复执行的脚本，实测它调用的工具与 Agent 内置工具完全一致，效果没有差别。实战中值得注意的是：本案例执行时 Blender 端早已由用户手动点击启动了服务（端口 9876 已监听），因此无论哪种形态，前置条件完全相同。

4.3 第一版：抛物面天线雷达站

第一版脚本（build_radar.py）一次性完成整站搭建，核心步骤如下：

1. 清理默认场景：全选删除默认的立方体、灯光与相机，并清理孤立数据块。
2. 搭建主体：锥形混凝土塔身（primitive_cone_add 生成上细下粗的柱体）、塔顶平台与栏杆、加强环、检修门。
3. 抛物面天线：用 bmesh 逐顶点生成真实抛物面网格（z = x² + y² / 4f），配合 Solidify 修改器加厚度，再放三根撑杆吊住馈源喇叭。
4. 材质：每种材质独立创建 Principled BSDF，混凝土、金属、玻璃、自发光信标灯各一套。
5. 灯光与天空：太阳光 + 物理天空（Nishita 类天空纹理），相机加 Track To 约束对准塔身。
6. 动画：在天线枢轴空物体的 rotation_euler 上插入关键帧（第 1 帧 0°、第 144 帧 360°），插值设为线性并加循环修改器，实现 6 秒/圈的匀速旋转。
7. 验证：保存 .blend 并调用 bpy.ops.render.render(write_still=True) 输出预览图，回传给 Agent 检查。

渲染图回传后由 Agent 自查，发现了画面过曝、天线顶部出画、地面边缘穿帮等问题，随后通过两轮迭代修正（拉远相机、降低曝光、扩大地面），第一版就此完成。

4.4 Blender 5.2 的 API 兼容坑

实战中首批报错几乎全部来自 Blender 版本迭代——网上大量教程代码基于 2.x/3.x，直接搬会报错。本案例实测遇到的兼容点整理如下，遇到类似报错可直接对照：

应对这类问题的通用策略：把报错原文交给 Agent，让它自行修改脚本重试。实测 AI 对这类 API 差异的自愈能力很强，本轮五处兼容问题均在两三次重试内自动解决。

4.5 需求变更：换成二次雷达天线

需求变更正是检验 MCP 工作流价值的场景。一句"把塔上的天线换成二次雷达天线"，Agent 执行的替换脚本做了三件事：按名称前缀删除旧的锅状天线组件；用 bmesh 生成二次雷达标志性的抛物柱面反射体（水平方向聚焦的弧形"帘状"幕墙）与焦线处的垂直馈电柱、振子单元；把新组件重新挂到原旋转枢轴上，6 秒/圈的旋转动画原样保留。

值得注意的是，删除旋转枢轴并不会删除它的子物体——旧组件会变成孤儿对象留在场景里。本案例在后续版本重建时就因为残留组件与场景重叠排查了一轮，排查方法是列出场景全部对象逐一核对，再按名称前缀精准删除。养成"改版后核对对象清单"的习惯能省掉很多隐形成本的排查。

4.6 按参考图重建：测地线雷达罩版本

提供一张真实高空雷达站的参考照片后，AI 据此把模型升级为更经典的造型：圆柱塔换成方形混凝土塔，塔顶加支撑环，环上放置测地线雷达罩——用细分二十面体叠加 Wireframe 修改器生成真实的三角网格蒙皮，罩内保留旋转天线。环境同步升级为"山脊云海"：地面缩小为山顶平台，下方放置一张自发光的巨大云海平面，天空改为纯色深蓝背景。

这一阶段最典型的经验是渲染验证驱动的多轮迭代：第一版渲染发现面板纹理过细、罩体比例偏小、天空发灰；第二轮放大罩体、改用测地线网格、提亮云海；第三轮修正太阳方位角——Agent 最初把太阳方位角算错，阳光打在塔身背面，导致正面全靠环境光照明、颜色发闷，修正后立面才真正"亮"起来。前后共五轮迭代，每一轮都由渲染图暴露问题、下一轮脚本解决问题。

4.7 意外断电后的恢复

建模进行到一半遭遇断电，重启后 Blender 自动恢复的是较早的自动存档，部分脚本成果丢失。这暴露了纯内存操作的风险，对应的恢复策略是：把全部建模命令合并成一个可重放的恢复脚本。具体做法是把会话中每一步 execute_blender_code 的代码按顺序拼接，剔除中间的渲染与保存调用，只在末尾保留一次保存与渲染，然后整段重新执行。

由于脚本从"清空场景"开始，重放与断电前的场景状态无关，可以从任何起点完整重建。重放完成后核对对象数量（58 个）与渲染效果，再保存一次 .blend。此后该恢复脚本就成为模型的"源代码"——.blend 文件损坏或误删时都可以随时从零重建。

4.8 罩内旋转天线与非渲染半透明

真实的高空雷达站台中，罩体是固定的射频透明外壳，旋转的是罩内天线。为此在雷达罩内部重建了天线组件（反射体、馈电柱、振子、支撑结构全部挂载在旋转枢轴上，动画与外置天线完全一致），并把罩体材质的 Alpha 设为 0.42、渲染方式设为 BLENDED，实现非渲染状态下的半透明。

这里有一个 Blender 视口机制需要了解：实体模式（Solid）不显示材质透明度，这是模式本身的限制；要看半透明效果需切换到材质预览模式（Material Preview）或渲染模式。实测还发现，个别插件若通过绘制回调在视口上强插面板，常规的隐藏区域属性无法将其去除，此时用 --factory-startup 参数以出厂设置启动演示实例即可获得纯净画面。

4.9 补充配套设施

真实站台还需要运营设施。围绕原有布局补充了六组设施：柴油发电机房（含排气烟囱与通风口）、两组立式储油罐与输油管、6 块 32° 倾角的太阳能电池板阵列、带半透明网格围网的前沿弧形围栏与大门、一辆停在大门内的工程皮卡与沥青车位、7 米旗杆与红旗，以及带旋转风速仪动画的气象站。其中风速仪与雷达天线一样通过枢轴关键帧实现循环旋转。

补充设施时有两个容易踩的坑。一是朝向必须按场景里的太阳实际方位计算：太阳能板初版法线朝北，与太阳入射方向夹角接近 90°，等于白装；按太阳方位角与高度角重算法线后，面板才真正朝向阳光。二是大型部件与塔身的遮挡关系：发电机房最初放在塔的正后方，从常见视角看只露出一个奇怪的黑色边角，挪到开阔位置后观感立刻改善。摆放设施后务必从主视角和俯视角各渲染一次检查。

5. 打包成可演示的 exe

5.1 打包思路

Blender 从 2.8 版本起移除了内置游戏引擎，因此没有官方的"导出成独立 exe"功能。实用的替代方案是一个"启动器 + 资源"的演示包：用 Windows 自带的 C# 编译器把一个几十行的启动器编译成 exe，双击后自动调用本机 Blender 打开模型文件，并注入一个自动演示脚本。

5.2 自动演示脚本

演示脚本（demo_autoplay.py）由启动器以 --python 参数注入，在模型加载完成后自动执行四件事：

# 1. 所有 3D 视口切换到材质预览模式并启用场景世界与场景灯光
space.shading.type = "MATERIAL"
space.shading.use_scene_world = True
space.shading.use_scene_lights = True

# 2. 隐藏全部编辑器干扰元素
space.show_region_ui = False
space.show_region_toolbar = False
space.overlay.show_floor = False
space.overlay.show_gizmo = False

# 3. 设置初始机位并启动循环动画
r3d.view_rotation = mathutils.Euler((math.radians(22), 0, math.radians(-40)), "XYZ").to_quaternion()
bpy.ops.screen.animation_start()

# 4. 注册定时器让视角绕站台缓慢环绕（每 0.03 秒转 0.14 度）
def orbit():
    dz = mathutils.Quaternion((0, 0, 1), math.radians(-0.14))
    r3d.view_rotation = (dz @ r3d.view_rotation).normalized()
    return 0.03
bpy.app.timers.register(orbit, persistent=True)

实测有两个经验值得记录：其一，视口最大化（screen_full_area）在启动横幅弹窗未关闭时可能失败，用带重试的定时器反复尝试直到成功即可；其二，慎用视口的 Rendered 渲染模式做演示，实测在部分显卡驱动上，半透明材质加场景世界的组合会直接导致 Blender 崩溃退出，材质预览模式则稳定得多，且视觉效果几乎一致。

5.3 编译启动器

启动器是一个极简的 C# 程序：优先查找便携化的本地 Blender 副本，找不到则回退到系统安装路径，然后以正确的参数启动 Blender。使用 Windows 自带的编译器一键编译：

C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe -nologo -target:winexe -out:RadarStationDemo.exe -r:System.Windows.Forms.dll -r:System.dll launcher.cs

string dir = AppDomain.CurrentDomain.BaseDirectory;
string[] candidates =
{
    Path.Combine(dir, "blender", "blender.exe"),                       // 便携副本优先
    @"C:\Program Files\Blender Foundation\Blender 5.2\blender.exe"     // 回退到系统安装
};
Process.Start(new ProcessStartInfo {
    FileName = blender,
    Arguments = string.Format("--factory-startup \"{0}\" --python \"{1}\"", blend, script),
    UseShellExecute = true
});

其中 --factory-startup 让 Blender 以出厂设置启动演示实例，避免用户自装的插件面板出现在演示画面里。最终演示包共四个文件：启动器 exe、模型 blend、演示脚本 py 与说明文档，双击 exe 即可全屏展示自动环绕、雷达旋转的完整效果。

6. 总结

6.1 核心内容回顾

• Blender MCP 由 MCP 服务器（uvx blender-mcp）与 Blender 插件两部分组成，二者通过 127.0.0.1:9876 通信，使用前必须启动 Blender 并连接插件服务。
• ZCode 侧在 config.json 的 mcp.servers 注册服务器，注意配置 timeoutMs 与 uv 镜像环境变量，并预热依赖包规避首次启动超时。
• execute_blender_code 是核心工具，AI 建模的本质是"需求、代码、渲染验证、迭代修复"的循环。
• Blender 5.2 相对旧版本有大量 API 变更，把报错原文交给 Agent 自行修复是最高效的排障方式。
• 断电或误操作后，用合并的"全量重放脚本"可以从零重建整个场景，建模脚本就是模型的源代码。
• 打包演示用"启动器 exe + blend + 自动脚本"组合，--factory-startup 保证演示画面纯净，视口演示优先使用材质预览模式保证稳定性。

6.2 常见问题与解答

问：ZCode 工具列表里看不到 blender-mcp 的工具怎么办？

答：MCP 工具只在会话启动时注册。确认配置正确、依赖已预热后，重启 ZCode 会话即可。若首次配置时未预热依赖，uvx 冷启动下载依赖包超过默认 30 秒超时也会导致注册失败，按 3.2 节配置 timeoutMs 并重启。

问：调用工具时报 "Failed to connect to Blender" 是什么原因？

答：Blender 没有运行，或插件内的 socket 服务没有启动。打开 Blender，在 3D 视口侧栏的 MCP for Blender 标签中点击连接按钮，再用 netstat -ano | findstr 9876 确认端口处于监听状态。

问：让 AI 执行建模脚本时报 AttributeError 或参数错误怎么办？

答：大概率是 Blender 版本 API 差异，把报错原文原样发给 Agent，让它根据报错自行修改脚本重试。本教程 4.4 节的对照表覆盖了 Blender 5.2 实测最常遇到的三类变更。

问：视口里看不到模型的半透明效果？

答：实体模式（Solid）不支持材质透明度。把视口着色模式切换为材质预览（Material Preview）即可看到半透明效果；注意个别显卡驱动上视口的 Rendered 渲染模式可能不稳定。

问：Blender 意外关闭，做了一半的模型丢了怎么办？

答：只要建模过程是通过脚本执行的，就可以把各步骤脚本按顺序合并成恢复脚本一次性重放重建。更稳妥的习惯是每完成一个阶段手动保存一次 .blend，Blender 的自动存档也会在崩溃后提供恢复入口。