Blender-MCP-Codex 安装调试教程：用 uvx 跑通 addon.py 与 TaoToken 配置

1. Blender-MCP-Codex 到底在解决什么问题如果你在 Blender 里做建模又想让 Codex 这类编码助手直接操作场景Blender-MCP-Codex 这套组合就是干这个的。它把 Blender 当成一个可以被自然语言驱动的工具Codex 负责理解你的意图并生成调用MCP 负责在中间传话Blender 里的 addon.py 负责真正执行建模动作。整条链路跑通之后你可以用一句话让 Codex 删掉立方体、建一个球体、甚至搭一张书桌而不用手点菜单。这套方案适合三类人一是经常用 Blender 做重复建模、想用脚本提效的二是已经在用 Codex 写代码、想把它扩展到 3D 场景的三是想研究 MCP 协议怎么和本地软件联动的。它不适合完全没碰过命令行的小白直接上生产项目因为 addon.py 里的 execute_blender_code 能在 Blender 里跑任意 Python行为约束靠提示词不是系统级沙箱。我实测下来最容易卡住的不是 Blender 插件本身而是 uvx 的 PATH、Codex 的 MCP 配置格式以及 TaoToken 统一 Key 怎么接进这条链路。下面按“先装环境、再配通道、最后验证”的顺序走每一步都给可复制的配置和排错点。2. 前置准备uv、Blender 插件与 TaoToken 通道2.1 安装 uv 并确认 uvx 可用README 要求用 uv并通过 uvx 启动 MCP 服务端。不要用 pip install uv 代替因为那样可能不会提供可用的 uvx 命令。在普通 PowerShell 里执行winget install --idastral-sh.uv -e装完关掉当前 PowerShell重新开一个窗口验证uvx --version能显示版本号就说明 uvx 进了 PATH。如果想知道它装在哪运行where.exe uvx把输出的完整路径记下来后面可以把这个绝对路径直接写进 Codex 配置避免 PATH 没刷新导致的“找不到命令”。2.2 安装 Blender 的 addon.py打开插件文件链接下载 addon.py然后在 Blender 里进入 编辑 → 偏好设置 → 插件右上角点“从磁盘安装”选中刚下载的 addon.py。安装完自动勾选 Blender MCP 启用插件。回到 3D 视图按 N 打开侧边栏找到 BlenderMCP 标签页Port 保持 9876点 Connect to MCP server。保持 Blender 不要关闭。2.3 用 TaoToken 统一 Key 与 API 通道这一步是很多人忽略的Codex 侧如果要调用模型能力最好把 Key 和 API 地址统一到一处管理而不是散落在各个配置文件里。TaoToken 提供统一的 Key 和 API 通道官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。你可以在控制台创建 Key然后把它写进 Codex 的配置里。需要先拿到 Key 的话去 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你打算长期用 Codex 做编码和 Agent 任务可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。模型对话调试入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。3. 可复制配置config.toml 与 settings.json 骨架3.1 Codex 的 MCP 配置settings.json 骨架打开 Codex 左下角齿轮 → 设置 → 插件右上角“添加 → 添加 MCP 服务器”选择添加本地服务。名称填 blender启动命令填 cmd参数填 /c uvx blender-mcp环境变量填{ mcpServers: { blender: { command: cmd, args: [/c, uvx, blender-mcp], env: { BLENDER_HOST: localhost, BLENDER_PORT: 9876, DISABLE_TELEMETRY: true } } } }保存后完全退出并重新打开 Codex再新建一个对话。MCP 服务端由 Codex 启动不需要另外开 PowerShell 手动跑 uvx blender-mcp。如果你把 uvx 装在了非默认路径把 args 里的 uvx 换成 where.exe uvx 输出的完整路径。3.2 TaoToken 的 config.toml 骨架如果你用支持 config.toml 的客户端接 TaoToken可以按下面这个骨架写。核心是把 base_url 指向 https://taotoken.net/api api_key 填你在控制台创建的 Key# TaoToken 统一通道配置骨架 [provider] name taotoken base_url https://taotoken.net/api api_key sk-你的TaoTokenKey [model] default claude-sonnet timeout_seconds 120 [mcp.blender] command cmd args [/c, uvx, blender-mcp] env { BLENDER_HOST localhost, BLENDER_PORT 9876, DISABLE_TELEMETRY true }注意 base_url 不要带 UTM 参数API 调用只认 https://taotoken.net/api 这个基址。Key 不要写进 Blender 工程文件也不要提交到 Git。3.3 addon.py 注册片段addon.py 安装后Blender 插件列表里会出现 Interface: Blender MCP。它的注册逻辑大致是这样理解这段有助于你排错bl_info { name: Blender MCP, author: MCPBlender, version: (1, 0), blender: (3, 0, 0), category: Interface, } def register(): bpy.utils.register_class(BlenderMCPPanel) bpy.utils.register_class(BlenderMCPConnect) def unregister(): bpy.utils.unregister_class(BlenderMCPConnect) bpy.utils.unregister_class(BlenderMCPPanel)如果插件装完没出现 BlenderMCP 标签页先看 Blender 控制台有没有 register 报错多半是 Blender 版本和 bl_info 里的 blender 版本不匹配。4. 验证请求从只读场景到创建球体4.1 只读验证确认 Blender 已打开、插件已启用、BlenderMCP 面板显示已连接后在 Codex 里先发一条只读指令只读取当前 Blender 场景信息不创建、不修改、不保存也不要执行任意 Python。成功的话会返回类似已只读获取当前 Blender 场景信息 场景Scene 对象3 个 CubeMESH[0, 0, 0] LightLIGHT[4.08, 1.01, 5.9] CameraCAMERA[7.36, -6.93, 4.96] 材质2 个 未创建、未修改、未保存也未执行任何 Python。这一步能过说明 Codex → MCP → addon.py → Blender 的读链路是通的。4.2 写入验证再发一条写入指令只在当前空白测试场景中删除立方体然后创建一个球体命名为 MCP_Test不要保存文件。在 Blender 界面里能看到立方体被删除原点位置出现一个球体右侧 Collection 里球体名称为 MCP_Test说明写链路也通了。4.3 启动日志与调用回显如果 Codex 侧看不到 Blender MCP 工具先看 MCP 服务端启动日志。正常启动会打印监听 localhost:9876 的信息。Blender 侧 BlenderMCP 面板显示已连接Codex 侧能看到 blender 工具列表两边对上才算真正连通。调用回显里如果出现 “Connection refused”基本是 Blender 没开或端口不是 9876。5. 本篇常见错排查5.1 uvx 找不到命令现象是 Codex 启动 MCP 时报 “uvx 不是内部或外部命令”。原因是 winget 装完没重开终端PATH 没刷新。解决关掉所有终端重开跑 uvx --version 确认还不行就用 where.exe uvx 拿绝对路径写进 settings.json 的 args。5.2 Blender 插件装了但没标签页多半是 Blender 版本低于 bl_info 里声明的版本或者安装时选错了文件。重新从磁盘安装 addon.py装完在插件列表搜 “Blender MCP”勾选启用。还不行就看 Blender 控制台的 register 报错。5.3 端口被占用或连不上9876 被别的进程占了BlenderMCP 面板会连不上。换一个端口同时改 Blender 面板的 Port 和 settings.json 里的 BLENDER_PORT两边必须一致。主机只用 localhost 或 127.0.0.1不要用 0.0.0.0。5.4 复杂任务超时把一个大任务拆成多个小任务先建模再材质再灯光再导出。一次让 Codex 干太多MCP 调用容易超时。实测拆成“创建基础结构 → 检查对象名称和尺寸 → 添加倒角和材质 → 调整灯光和相机 → 确认后保存或导出”这样的小步成功率高很多。5.5 安全边界execute_blender_code 能在 Blender 里执行任意 Python它不是严格沙箱提示词里的“不要访问文件”只是行为约束。建议第一次只用空白测试文件打开正式项目先另存备份Blender、Codex 和 MCP 服务都不要以管理员身份运行暂时不要启用 Poly Haven、Sketchfab、Hyper3D、Hunyuan3D 等外部资源功能也不要在 Blender 里保存密码或 API Key。6. 完成标准与后续接入满足这几条就算调试完成uvx --version 正常返回版本号Blender 中已启用 Interface: Blender MCPBlenderMCP 面板已连接到 localhost:9876Codex 中能看到 Blender MCP 工具Codex 能读取场景信息Codex 能在测试场景中创建并修改一个球体整个过程没开管理员权限也没改正式项目文件。后续如果你要把这条链路接到统一通道上Key 和 API 地址在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 管理接入细节看 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期做编码和 Agent 任务的话Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。模型对话调试用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。控制台入口是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Claude Code 相关配置参考 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。