用 Codex 操控 Blender 做 3D 场景：从安装 addon 到跑通第一条指令

用自然语言描述一个 3D 场景，然后看着 Blender 自动创建出来——这不是科幻，是 blender-mcp 现在能做到的事。blender-mcp 是一个开源 MCP（Model Context Protocol）服务器，把 Blender 暴露给 AI 工具，让任何支持 MCP 的 AI 工具（包括 Codex）都能直接操控 Blender 的场景、对象、材质、灯光和摄像机。

项目地址：ahujasid/blender-mcp，24,500+ stars。官方文档主要介绍的是 Claude 接入方式，Codex 的接入方法略有不同，而且有一个非常容易踩的配置坑，本文重点讲这部分。

需要准备什么

• Blender：3.0 或更新版本
• Codex CLI：已安装并登录
• uv / uvx：blender-mcp 通过 uvx 启动（不要用 pip install）
• Python 3.10+

安装 uv（选对应平台）：

# macOSbrewinstalluv# Linuxcurl-LsSfhttps://astral.sh/uv/install.sh|sh# Windows PowerShellpowershell-c"irm https://astral.sh/uv/install.ps1 | iex"

⚠️ 不要用pip install uv，这不会创建uvx命令，MCP 启动时会报spawn uvx ENOENT。

Step 1：在 Blender 里安装 addon

blender-mcp 由两部分组成：Blender 内运行的 addon，和 AI 工具通过 MCP 协议连接的 Python 服务器。

1. 前往github.com/ahujasid/blender-mcp→ Releases → 下载最新的addon.py
2. 打开 Blender →Edit → Preferences → Add-ons
3. 点击Install…→ 选择刚下载的addon.py
4. 在 Add-ons 列表里找到Interface: Blender MCP→ 勾选启用

安装完成后，在 3D 视图里按N键打开侧边栏，你会看到一个新的BlenderMCP标签。

Step 2：在 Codex 里配置 blender-mcp

方式 A：命令行一键添加（推荐）

codex mcpaddblender -- uvx blender-mcp

这条命令会自动把下面的内容写入~/.codex/config.toml，不需要手动编辑。

方式 B：手动编辑 config.toml

打开~/.codex/config.toml，添加：

[mcp_servers.blender] command = "uvx" args = ["blender-mcp"]

最容易踩的坑：mcp_servers和mcp.servers不一样

Codex 的 GitHub issue tracker 上有一个高赞 bug report（issue #3441）：用户配置了 MCP 服务器但 Codex 完全看不到它，无论怎么操作都无效。

原因就一个：把[mcp_servers.blender]写成了[mcp.servers.blender]（或[mcp.servers."blender"]）。

正确写法：

[mcp_servers.blender] command = "uvx" args = ["blender-mcp"]

错误写法（MCP 完全不加载）：

[mcp.servers.blender] # ❌ 错了 command = "uvx" args = ["blender-mcp"]

两者的格式几乎一样，但 Codex 只认mcp_servers，使用mcp.servers会导致整个 MCP 配置被静默忽略。

验证 MCP 是否加载成功：启动 Codex 后在 TUI 里输入/mcp，应该能看到 blender 服务器和它提供的工具列表。

Step 3：启动连接

1. 启动 Codex（CLI 或桌面端）
2. 切到 Blender，在侧边栏BlenderMCP标签里点击Connect to Claude（这个按钮在各种 AI 工具接入时都叫这个名字）
3. 等待连接建立——Blender 状态栏底部会显示连接状态

连接建立后，Codex 里的工具列表（/mcp）应该能看到 blender 服务器下的具体工具，比如get_scene_info、create_object、execute_blender_code等。

其他常见问题

spawn uvx ENOENT错误

发生原因：Codex 桌面端从 GUI 启动时不继承终端的 PATH，找不到 uvx 的位置。

解决方法：用 uvx 的完整路径：

# 查找完整路径whichuvx# 通常是 /opt/homebrew/bin/uvx (macOS) 或 ~/.local/bin/uvx (Linux)

然后在 config.toml 里用完整路径：

[mcp_servers.blender] command = "/opt/homebrew/bin/uvx" args = ["blender-mcp"]

项目级 config 不生效

在项目目录下创建.codex/config.toml配置 MCP 时，需要先把该目录加入 Codex 的受信任目录列表（在~/.codex/config.toml里），否则项目级 MCP 配置会被忽略。

首次连接超时

uvx 首次运行会下载 blender-mcp 包，耗时较长。可以增加启动超时：

[mcp_servers.blender] command = "uvx" args = ["blender-mcp"] startup_timeout_sec = 30

不要同时开两个 MCP 实例

blender-mcp README 明确警告：不要在 Codex 和 Claude Desktop（或其他工具）里同时运行 blender-mcp 服务器，会产生冲突。同一时间只开一个。

连接成功后能做什么

blender-mcp 暴露的能力包括：

• 场景信息：获取当前场景的对象列表、层次结构、材质状态
• 对象操作：创建、移动、缩放、旋转、删除 3D 对象
• 材质控制：应用颜色、创建材质、修改 PBR 参数
• 灯光与摄像机：调整光源参数、设置摄像机角度和焦距
• 执行 Python 代码：直接在 Blender 里运行任意 Python 脚本（强大但需谨慎）
• Poly Haven 资产：通过 API 搜索和导入模型、材质、HDRI
• Hyper3D 生成：用文字描述生成 3D 模型

示例对话（向 Codex 发出）：

• 查看当前 Blender 场景里有哪些对象，然后帮我把所有灯光的强度调高 50%
• 创建一个低多边形风格的城堡场景，包含塔楼、城墙和护城河
• 把选中对象的材质改成金属质感，粗糙度 0.2，添加轻微反射

附：Blender 官方 MCP vs blender-mcp

Blender 官方也在 2026 年 Q1 推出了自己的 MCP 服务器（projects.blender.org/lab/blender_mcp），定位是提供 Blender Python API 的自然语言接口，侧重文档查询和 API 探索。

两者定位不同：官方 MCP 更适合"我想了解某个 Blender API 怎么用"的文档辅助场景；ahujasid/blender-mcp更适合"我想让 AI 直接操控场景"的创作场景。

结语

整个接入流程不复杂，唯一需要特别注意的是mcp_servers的拼写——这是绝大多数人配置失败的唯一原因。配置对了之后，Codex 操控 Blender 的体验非常流畅，特别是批量修改对象属性和执行复杂 Python 脚本这类任务。

本文基于 blender-mcp 官方 README 和 Codex 官方 MCP 配置文档（learn.chatgpt.com/docs/extend/mcp）。

参考资料

• blender-mcp GitHub：github.com/ahujasid/blender-mcp
• blender-mcp 官网：blendermcp.org
• Codex MCP 官方文档：learn.chatgpt.com/docs/extend/mcp
• Codex 编程接入：qiniu.com/ai/plan
• Blender 官方 MCP：blender.org/lab/mcp-server