1. Blender 手动调参的痛点与 AI3D 协作场景如果你用过 Blender 做过稍微复杂一点的场景大概都经历过这种循环加一个立方体调尺寸改材质发现光照不对回去改相机角度再回来调材质节点……一个下午过去场景里还是那几个几何体。Blender 本身不复杂复杂的是「参数之间的联动关系」——你改一个数值另外三个地方跟着变而你的大脑要同时记住这些依赖。我试过用脚本批量生成物体但写 Python 脚本本身又变成了新的调参工作bpy.ops.mesh.primitive_cube_add(size2, location(0,0,0))这种代码写多了也累而且每次改需求都要回去改脚本。真正想要的是用自然语言描述我想要什么让 AI 直接操作 Blender 完成建模、UV 展开和参数调整。这就是 Blender-MCP 要解决的问题。MCP 是 Model Context Protocol 的缩写你可以把它理解成「AI 和本地软件之间的 USB 接口」——Claude 通过这个接口向 Blender 发送指令Blender 执行后把结果返回给 Claude形成一个闭环。Blender-MCP 就是专门为 Blender 写的这个接口。具体能做什么举几个我实际跑通的例子「创建一个低多边形地下城场景有一条龙守着一罐金币」——Claude 会依次创建地面、墙壁、龙的低模、金币罐并设置材质和位置「把这个球体的 UV 展开成智能投影然后导出 UV 布局图」——Claude 调用 Blender 的 UV 展开算子完成后告诉你结果「把场景里所有金属材质的粗糙度从 0.5 改成 0.2」——Claude 遍历材质节点批量修改参数适合谁三类人一是刚学 Blender 不想被参数淹没的新手二是需要快速出概念草图的 3D 设计师三是想用 AI 辅助批量处理 UV、材质等重复工作的技术美术。整个链路在本地跑Blender 和 Claude 都在你自己机器上不需要把模型文件传到任何云端。下面我从环境准备开始一步步带你把这套链路跑通。过程中会给出可复制的配置片段和提示词模板你跟着做就能复现。2. TaoToken 前置准备获取 API Key 与 Claude Code 接入配置Blender-MCP 本身是一个 MCP Server它需要和一个支持 MCP 的 AI 客户端配合。Claude Desktop 是最直接的选择但如果你想像我一样在命令行里用 Claude Code 来驱动 Blender就需要先有一个能用的 API 通道。这里我用 TaoToken 来做接入它的 API 端点兼容 Anthropic 的接口格式配置起来比较直接。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 API Key复制出来备用。这个 Key 就是后面配置文件里要填的凭证。如果你用的是 Claude Code CLI接入方式是在终端里设置环境变量。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 Base URL 使用。在~/.claude/settings.json或者项目级的.claude/settings.json里写入{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key } }保存后在终端执行claude进入交互界面输入/status确认连接正常。如果显示当前模型和 API 端点信息说明 Key 已经生效。如果你更习惯用 Claude Desktop 的图形界面那 Key 的配置方式不同——Claude Desktop 本身不直接读环境变量而是通过claude_desktop_config.json来配置 MCP Server。但 Claude Desktop 需要你已经有 Anthropic 官方的账号登录TaoToken 的 Key 在这里主要用于 Claude Code CLI 的场景。两种方式选一种就行我下面会分别给出配置。还有一个东西需要提前装好uv。Blender-MCP 的启动命令是uvx blender-mcpuvx是 uv 包管理器提供的工具运行器它会自动下载并运行 blender-mcp 这个包不需要你手动 pip install。Windows 下用 PowerShell 安装powershell -c irm https://astral.sh/uv/install.ps1 | iex安装完成后把 uv 的可执行目录加到用户 PATH$localBin $env:USERPROFILE\.local\bin $userPath [Environment]::GetEnvironmentVariable(Path, User) [Environment]::SetEnvironmentVariable(Path, $userPath;$localBin, User)macOS 下更简单brew install uv验证安装uv --version能输出版本号就说明 uv 就绪了。这一步看起来简单但后面 Claude 启动 MCP Server 时如果找不到uvx命令整个链路就断了所以务必确认uvx --version也能正常输出。Blender 本身需要 3.0 或更高版本Python 3.10。这些是基础环境不展开讲。重点在于Blender 要开启一个本地 Socket 服务Claude 通过 MCP Server 连接到这个 Socket才能向 Blender 发送 Python 指令。这个 Socket 的配置在下一节。3. 可复制配置Blender-MCP 插件安装与 claude_desktop_config.json 完整片段这一节是整篇文章的核心操作部分我会把每一步的配置片段都写全你直接复制就能用。3.1 安装 Blender-MCP 插件先从 Blender-MCP 的 GitHub 仓库下载最新的.zip包搜索blender-mcp就能找到。解压后进入包含addon.py的文件夹复制这个文件夹的完整路径。打开 Blender点击左上角Edit→Preferences→Add-ons点击右上角的Install from Disk...在弹出的文件选择框里粘贴刚才复制的路径选中addon.py点击安装。安装完成后在插件列表里搜索BlenderMCP勾选启用。回到 Blender 主界面按键盘上的N键右侧会弹出一个侧边栏里面多了一个BlenderMCP标签页。点击它你会看到端口设置默认 9876和一个Connect按钮。先不要点连接等 Claude 那边配置好之后再点。3.2 配置 Claude Desktop 的 MCP Server找到 Claude Desktop 的配置文件。路径因系统而异macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json如果文件不存在就新建一个。写入以下内容{ mcpServers: { blender: { command: uvx, args: [blender-mcp] } } }这个配置告诉 Claude Desktop有一个叫blender的 MCP Server启动方式是运行uvx blender-mcp。Claude 启动时会自动拉起这个进程进程内部会去连接 Blender 的 9876 端口。保存文件后完全退出 Claude Desktop不是关窗口是退出进程重新打开。点击设置里的Developer标签如果看到blender出现在 MCP Server 列表里并且状态是 running说明配置成功。3.3 如果你用 Claude Code CLIClaude Code 添加 MCP Server 只需要一行命令claude mcp add blender uvx blender-mcp执行后可以用claude mcp list确认。然后在 Claude Code 的交互界面里Claude 就能调用 Blender 的工具了。3.4 关键配置项对照配置项值说明MCP Server 名称blender在 Claude 里引用时的标识启动命令uvxuv 提供的工具运行器参数blender-mcpPyPI 上的包名Blender 端口9876插件默认监听端口连接方式本地 Socket不走网络仅本机通信配置完成后回到 Blender 的BlenderMCP面板点击Connect。如果 Claude Desktop 已经启动你会看到 Blender 的终端输出里出现连接日志。此时在 Claude 对话框里输入「列出当前场景中的所有物体」Claude 会调用 MCP 工具Blender 返回场景信息。这就是链路打通的标志。注意Blender 插件和 Claude Desktop 的启动顺序不影响连接因为 MCP Server 是 Claude 启动时拉起的它会主动去连 Blender 的端口。但如果 Blender 没开或者没点 ConnectClaude 调用工具时会报连接超时。4. 验证请求从建模到 UV 展开的完整成功结果演示配置好之后我们来跑一个完整的验证流程。我会用一个具体的场景来演示创建一个低多边形风格的房间里面有一个悬浮的金属球体然后对球体做 UV 展开并导出 UV 布局图。4.1 第一步清空场景并创建基础几何体在 Claude 对话框里输入清空当前场景中的所有物体然后创建一个 10x10 的地面平面一个位于 (0, 0, 2) 的 UV 球体半径 1.5。给球体添加一个金属材质基础色设为红色粗糙度 0.2。Claude 会依次调用 Blender 的 Python API先bpy.ops.object.select_all(actionSELECT)然后bpy.ops.object.delete()清空场景接着创建平面和球体最后通过bpy.data.materials.new()创建材质并赋值给球体。你会在 Blender 视口里实时看到物体出现。如果没看到按一下小键盘的0切换到相机视角或者按Home键让视图适配所有物体。4.2 第二步设置光照和相机继续输入添加一个区域光位置在 (5, -5, 8)能量设为 1000W朝向球体。把相机移动到 (8, -8, 6)看向球体设置焦距为 50mm。Claude 会创建AREA类型的光源设置energy属性然后调整相机的location和rotation_euler。这里有个细节Claude 需要计算相机看向球体的旋转角度它会用 Blender 的Vector和to_track_quat方法来实现。4.3 第三步UV 展开这是验证 AI3D 链路是否完整的关键步骤。输入选中球体进入编辑模式全选所有面执行智能 UV 投影角度限制 66 度岛边距 0.02。然后退出编辑模式导出 UV 布局图到桌面文件名 uv_layout.png。Claude 会执行bpy.ops.object.mode_set(modeEDIT) bpy.ops.mesh.select_all(actionSELECT) bpy.ops.uv.smart_project(angle_limit1.15192, island_margin0.02) bpy.ops.object.mode_set(modeOBJECT) bpy.ops.uv.export_layout(filepath~/Desktop/uv_layout.png, size(1024, 1024))注意angle_limit参数在 Blender Python API 里是弧度制66 度约等于 1.15192 弧度。Claude 会自动做这个转换。执行完成后桌面上会出现uv_layout.png打开就能看到球体的 UV 展开图。4.4 第四步批量参数调整最后验证一下批量修改能力把场景中所有材质的粗糙度参数乘以 0.5然后把球体的位置向上移动 1 个单位。Claude 会遍历bpy.data.materials找到每个材质的 Principled BSDF 节点修改Roughness输入值。然后修改球体的location.z。整个流程跑下来你不需要手动在 Blender 界面里点任何按钮全部通过自然语言完成。这就是 Blender-MCP Claude 的核心价值把操作意图和 Blender 的 API 调用之间的翻译工作交给 AI。如果你在验证过程中遇到 Claude 说「我无法直接操作 Blender」或者工具调用没有反应大概率是 MCP Server 没连上。回到第 3 节检查claude_desktop_config.json的路径和内容确认 Blender 插件面板里的 Connect 按钮已经点击并且显示已连接。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth 报错这一节整理我在配置过程中实际踩到的报错和对应的解法。如果你卡在某一步先在这里找找有没有匹配的错误信息。5.1 401 Unauthorized现象Claude Code 启动后调用 API 返回 401提示invalid api key或authentication_error。原因ANTHROPIC_API_KEY没有正确设置或者 Key 已经失效。排查在终端执行echo $ANTHROPIC_API_KEYmacOS/Linux或echo %ANTHROPIC_API_KEY%Windows确认输出的 Key 和你在 TaoToken 控制台创建的一致。如果为空检查settings.json里的env字段是否写对JSON 格式有没有多逗号或少引号。另外确认ANTHROPIC_BASE_URL是https://taotoken.net/api不要在后面加/v1或其他路径。5.2 local proxy failed / connection refused现象Claude Desktop 启动时 MCP Server 状态显示 failed日志里有local proxy failed或ECONNREFUSED。原因uvx命令找不到或者 Blender 的 9876 端口没有监听。排查先在终端手动执行uvx blender-mcp看是否能正常启动。如果报command not found说明 uv 的 bin 目录没加到 PATH。Windows 下重新执行第 2 节的 PATH 设置命令然后重启 Claude Desktop。如果uvx能启动但 Claude 里还是 failed检查 Blender 插件面板是否点了 Connect。Blender 不点 Connect9876 端口就不会监听MCP Server 连不上。5.3 reading choices / unexpected end of JSON现象Claude 调用 MCP 工具时返回error reading choices或unexpected end of JSON input。原因MCP Server 和 Blender 之间的通信数据格式异常通常是 Blender 插件版本和 blender-mcp 包版本不匹配。排查确认 Blender-MCP 插件是从官方仓库下载的最新版uvx blender-mcp会自动拉取 PyPI 上的最新包。如果问题持续在 Blender 插件面板里断开连接重启 Blender再重新 Connect。然后在 Claude 里重新发起请求。5.4 OAuth token exchange failed现象Claude Code 启动时提示 OAuth 相关错误无法进入交互界面。原因Claude Code 默认走 Anthropic 的 OAuth 登录流程如果你用的是 API Key 方式需要确保没有残留的 OAuth 凭证。排查删除~/.claude/下的credentials.json如果存在然后在settings.json里明确配置ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL。重启终端后再执行claude。如果还是报 OAuth 错误检查是否有环境变量CLAUDE_CODE_USE_OAUTH被设置为 true把它删掉或设为 false。5.5 工具调用无响应现象Claude 说「我将调用 Blender 工具」但之后没有任何输出Blender 也没有反应。原因MCP Server 进程卡死或者 Blender 主线程被阻塞。排查在 Claude Desktop 的设置 → Developer 里把 blender MCP Server 停止再启动。如果用的是 Claude Code CLI退出后重新执行claude mcp add blender uvx blender-mcp覆盖配置。Blender 那边如果正在执行耗时操作比如复杂布尔运算主线程会阻塞等操作完成后再试。5.6 配置三件套检查清单无论遇到哪种报错先确认这三个东西都写对了组件检查项正确值Base URL是否带多余路径https://taotoken.net/apiAPI Key是否复制完整sk-开头无空格Model IDClaude Code 默认模型claude-sonnet-4-20250514或按需指定如果用的是 Claude Desktop 而不是 Claude CodeBase URL 和 Key 的配置在 Claude Desktop 自己的账号体系里MCP 配置只负责uvx blender-mcp这一件事。两种方式的配置不要混在一起。6. 从提示词模板到长期 AI3D 工作流Coding Plan 与接入文档链路跑通之后真正影响效率的是提示词的质量。我整理了几个在实际项目中反复用到的模板你可以直接拿去改。建模类提示词创建一个 [风格] 风格的 [物体名称]主要尺寸为 [长x宽x高]放置在场景的 [位置]。使用 [材质类型] 材质基础色为 [颜色]粗糙度 [数值]金属度 [数值]。如果场景中没有灯光添加一个 [灯光类型] 在 [位置]能量 [数值]W。UV 类提示词选中 [物体名称]进入编辑模式全选所有面执行 [UV展开方式] 投影角度限制 [度数] 度岛边距 [数值]。完成后导出 UV 布局图到 [路径]分辨率 [尺寸]。批量调整类提示词遍历场景中所有 [材质/物体/灯光]把 [属性名] 从 [原值] 改为 [新值]。如果属性不存在则跳过最后报告修改了多少个对象。这些模板的核心思路是把 Blender 的操作步骤翻译成「对象 动作 参数」的结构Claude 就能准确映射到对应的 Python API 调用。如果你打算长期用这套工作流建议把常用的提示词存成文本片段或者写一个简单的 shell 脚本用claude -p 你的提示词的方式批量执行。Claude Code 支持非交互模式可以集成到 CI 流程里做自动化资产检查。对于需要频繁调用 API 的场景TaoToken 的 Coding Plan 提供了更稳定的配额和并发支持适合把 Blender-MCP 的调用集成到日常开发流程里。具体的接入方式和配额说明在 https://taotoken.net/coding-plan 可以查到。完整的 MCP 配置文档和 API 参数说明在 https://taotoken.net/doc 里面包含了 Claude Code、Cline、Codex 等不同客户端的接入示例。如果你在配置claude_desktop_config.json时需要确认字段格式或者想了解 MCP 协议的其他用法这份文档可以作为参考。最后说一个实际经验Blender-MCP 的稳定性很大程度上取决于 Blender 主线程的响应速度。如果你的场景面数超过 50 万Claude 的每次工具调用都会等 Blender 执行完才返回交互会变慢。这种情况下建议把复杂场景拆成多个小场景分别处理或者先用低模做布局确认无误后再用 Blender 自己的细分修改器提高精度。AI 负责的是「快速试错和批量操作」精细调整还是得靠你自己的审美判断。