Qoder + Blender MCP：对话建模到网页渲染在 Qoder 对话里通过 mcp-for-blender 驱

摘要

在 Qoder 对话里通过 mcp-for-blender 驱动 Blender，用自然语言完成建模、改材质、渲染校验和 GLB 导出，再用 three.js + GSAP 做成可滚动旋转的网页。流程本身不复杂，前提是把 Blender 插件、uvx 和 Qoder MCP 三项配置打通，之后每步脚本都经确认再执行。

流程图

循环部分对应“改脚本—再执行—再验证”，确认和报错都不会被自动跳过；渲染校验通过后才进入导出和网页环节。

前期配置步骤

1. 安装 Blender

安装官方稳定版 Blender 5.2.1，确认版本一致后再装插件。

2. 安装 uv / uvx

brew install uv
uvx --version

没有 Homebrew 时可用官方脚本：curl -LsSf https://astral.sh/uv/install.sh | sh。记下 which uvx 的输出路径，后面 MCP 配置要用绝对路径（本机为 /opt/homebrew/bin/uvx）。

3. 安装 Blender 插件

从 mcp-for-blender.com 或 GitHub（ahujasid/blender-mcp）获取插件文件 blender_mcp.py，然后在 Blender 中：

打开 编辑 > 偏好设置 > 插件
点右上角下拉菜单，选择“从磁盘安装”
选中 blender_mcp.py，勾选启用 “MCP for Blender”
插件与服务端都带遥测开关，保持关闭即可（服务端在 mcp.json 里设置）

4. 启动 Blender 侧服务

在 3D 视图按 N 打开侧栏，切到 “MCP for Blender” 标签页，确认端口为 9876，点击 “Connect to MCP server”。面板显示 Connected on localhost:9876 即表示 Blender 侧已就绪。

5. 配置 Qoder MCP

编辑 ~/.qoder-cn/mcp.json（Windows 路径不同）：

{
  "mcpServers": {
    "blender": {
      "command": "/opt/homebrew/bin/uvx",
      "args": ["mcp-for-blender==2.2.7"],
      "env": {
        "BLENDER_MCP_SAFE_MODE": "1",
        "DISABLE_TELEMETRY": "true"
      }
    }
  }
}

command 必须是 uvx 的绝对路径，GUI 启动的 Qoder 通常读不到 shell 的 PATH
BLENDER_MCP_SAFE_MODE=1 保持开启，脚本执行会受额外限制
版本与插件协议匹配，升级时两边一起看

6. 重载并验证链路

在 Qoder 设置里刷新 MCP 或重启应用，新开一个对话，确认能看到 Blender 相关工具。第一次验证可以让助手读取场景信息或截一张视口图，成功再开始建模。若工具未出现，先检查 9876 端口和 mcp.json 路径，再重载 MCP。

7. 建立项目目录与规则

~/BlenderProjects/
├── AGENTS.md      # 执行审批、安全、备份、命名规则
├── scripts/       # 可复用的 bpy 脚本
├── saves/         # 各阶段 .blend 副本
├── renders/       # 校验渲染图
├── exports/       # 导出的 GLB
└── web/           # 网页与本地预览

AGENTS.md 里至少写清：执行前说明影响、完整脚本等待“确认执行”、报错原样返回、删除按精确名称、破坏性操作先备份、QODER_ 前缀。

8. 准备网页侧

GLB 托管：对象存储桶设为公开读，并允许网页域名跨域
页面依赖：three.js 0.169.0、GSAP 3.12.5 走 jsDelivr，锁定版本
本地预览：cd ~/BlenderProjects/web && python3 -m http.server 8123

检查项	期望结果
`uvx --version`	正常输出版本号
`lsof -i :9876`	Blender 正在监听
Qoder 工具列表	出现 Blender 相关工具
读取场景	返回对象列表而不是报错
`http://localhost:8123`	页面能正常打开

操作流程

1. 对话生成模型

先说清尺寸、颜色、参考图和“只需外观模型”，减少来回改
按机身 → 部件 → 材质 → 灯光相机 → 渲染分阶段推进，每段单独确认
修改直接用自然语言描述，例如“去掉地面”“换成银色”，由助手改脚本
每阶段结束看视口或渲染图，确认无误再继续

2. 脚本审批与执行

执行前先说明目标、影响物体和风险
助手输出完整脚本，用户回复“确认执行”后才通过 MCP 运行一次
报错原样返回，不自动重试、不擅自改代码；修正后再执行
删除对象按精确名称，破坏性操作前先保存副本

3. 验证与导出

用多个角度渲染检查外形、比例和关键结构
删除只用于渲染的地面、道具等临时物体
只选中模型物体导出 GLB，使用 Y-up，不导出灯光和相机
留意面数和文件大小，控制网页加载成本

4. 网页渲染

three.js 加载 GLB，用环境贴图提供 IBL，金属材质才不会发黑
使用 ACES 色调映射和适度曝光，避免高光死白
预览页加轨道控制器；展示页用 GSAP 滚动驱动旋转与文字动效
最终在浏览器里实际打开检查，不能只看代码

5. 部署与引用

GLB 上传对象存储，确保公开读和 CORS；也可内嵌 base64，但页面会明显变大
渲染库走 CDN，避免本地路径在外部站点失效
本地用 HTTP 服务预览；上线后检查模型、脚本和字体等资源的可达性

注意事项

情况	注意点
safe mode 拦截脚本	`os`、`datetime`、`nonlocal` 等会被拒绝，脚本尽量只用 bpy 和字符串路径
中文界面节点找不到	按 `bl_idname` 查找节点，不要按显示名称
网页里金属发黑或过曝	必须补环境光（IBL），并用色调映射压住高光
模型到网页效果变差	glTF 只保留 PBR 材质，环境光和灯光要在网页端重建
屏幕、自发光异常	程序化材质导出会降级，加载后需要修正材质参数
双击 HTML 打不开	ES module 需要 HTTP 服务，不能直接 `file://` 打开
外部站点加载失败	检查存储桶权限、CORS、CDN 是否可达
Qoder 里看不到 Blender 工具	检查 `mcp.json` 绝对路径和 9876 端口，重载 MCP 后新开对话
误删或覆盖场景	执行前备份，按精确对象名删除，不碰非任务物体

Qoder + Blender MCP：对话建模到网页渲染

摘要

流程图