1. BlenderMCP 到底解决什么问题BlenderMCP 是一个把 Blender 3D 软件和模型上下文协议MCP打通的集成工具核心能力是让 AI 通过标准协议直接操控 Blender 场景创建对象、改材质、执行 Python 脚本、读取当前场景结构。它适合三类人一是想在 Blender 里用自然语言快速搭场景的 3D 爱好者二是需要批量处理模型资产的独立开发者三是想把 AI 能力接进现有 DCC 工作流的技术美术。它的通信结构分两层。第一层是 Blender 插件addon.py在 Blender 内部起一个基于 JSON 的 TCP socket 服务器默认监听 9876 端口负责真正执行 Blender 的 Python API。第二层是 MCP 服务器server.py实现模型上下文协议把 AI 侧发来的工具调用翻译成 socket 命令发给插件。AI 模型本身不直接连 Blender而是通过 MCP 服务器中转。问题就出在这个中转环节。MCP 服务器需要调用模型能力来理解你的指令、生成 Blender Python 代码而模型调用需要 API Key 和稳定的通道。如果你用的是官方直连会遇到几个现实麻烦Key 分散在多个地方管理、不同模型的接入地址不统一、切换模型要改一堆配置、团队协作时 Key 没法安全共享。我试过在三个项目里分别维护不同的 Key最后自己都记不清哪个对应哪个。TaoToken 在这里的角色是统一 Key 和 API 通道。你把模型调用统一走 TaoToken 的 API 地址MCP 服务器只需要配置一个 base_url 和一个 Key就能调用多种模型。这样 BlenderMCP 的配置从「每个模型一套参数」变成「一套参数调所有模型」切换模型只改一个模型名字段。下面从环境准备开始一步步把配置和验证做完。2. 前置准备环境、Key 与目录结构在动配置文件之前先把基础环境确认清楚。BlenderMCP 对版本有要求版本不对会在插件加载阶段就报错。Blender 需要 3.0 或更新版本建议直接用 4.x 稳定版。Python 需要 3.10 以上因为 MCP 服务器依赖的一些库在这个版本才有。包管理器推荐 uv它比 pip 快很多而且能自动处理虚拟环境。Mac 上装 uv 用brew install uvWindows 上用 PowerShell 脚本安装后记得把安装目录加进 PATH。TaoToken 这边你需要准备两样东西API Key 和接入地址。Key 在控制台的 API Keys 页面创建接入地址统一用https://taotoken.net/api。这个地址是 OpenAI 兼容格式的所以任何支持自定义 base_url 的客户端都能接。创建 Key 的时候建议按用途命名比如blender-mcp-dev方便后面排查问题时定位。目录结构建议这样组织避免路径混乱blender-mcp/ ├── src/ │ └── blender_mcp/ │ └── server.py ├── config.toml ├── settings.json └── .envconfig.toml放 MCP 服务器的模型接入配置settings.json放客户端侧的 MCP 服务器注册信息.env放 Key 等敏感变量。这样分层的目的是Key 不进版本库配置可以随项目走客户端注册信息独立于项目。注意.env文件一定要加进.gitignoreKey 泄露是接入环节最常见的安全事故。3. 可复制配置config.toml 与 settings.json 骨架这一节给出可以直接复制的配置骨架。先看config.toml这是 MCP 服务器读取的模型接入配置[model] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model_name claude-sonnet-4-20250514 max_tokens 8192 temperature 0.2 [blender] host 127.0.0.1 port 9876 timeout 30 [mcp] server_name blender-mcp transport stdio几个关键字段说明。base_url固定填 TaoToken 的 API 地址不要带末尾斜杠。api_key用${TAOTOKEN_API_KEY}引用环境变量不要硬编码。model_name按你实际要用的模型填切换模型只改这一行。temperature建议设低一点因为 Blender 代码生成需要确定性0.2 左右比较稳。[blender]段的 host 和 port 要和 Blender 插件里显示的一致默认就是 127.0.0.1:9876。再看settings.json这是客户端侧注册 MCP 服务器的配置以 Claude Desktop 为例{ mcpServers: { blender-mcp: { command: uv, args: [ --directory, /absolute/path/to/blender-mcp, run, src/blender_mcp/server.py ], env: { TAOTOKEN_API_KEY: sk-your-key-here, BLENDER_HOST: 127.0.0.1, BLENDER_PORT: 9876 } } } }command用 uv 启动--directory后面必须是绝对路径相对路径在客户端启动时会找不到。env段把 Key 和 Blender 连接信息注入 MCP 服务器进程。如果你用 CC Switch 管理多个 MCP 服务器配置片段是这样的{ name: blender-mcp, type: stdio, command: uv, args: [--directory, /absolute/path/to/blender-mcp, run, src/blender_mcp/server.py], env: { TAOTOKEN_API_KEY: sk-your-key-here }, enabled: true }CC Switch 的好处是可以在多个 MCP 服务器之间快速切换启用状态调试时不用反复改 settings.json。配置写完后Blender 插件那边也要装好下载 addon.py在 Blender 的 Edit Preferences Add-ons 里点 Install 选中文件然后勾选启用。启用后在 3D 视图按 N 键侧边栏会出现 BlenderMCP 标签页。4. 连通性验证从启动到成功执行配置写完不代表能用必须做连通性验证。验证分三步每步都有明确的成功标志。第一步验证 TaoToken API 通道本身通不通。用 curl 发一个最小请求curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: reply with ok}], max_tokens: 10 }返回里如果有choices字段且内容正常说明 Key 和通道都没问题。如果返回 401是 Key 错了返回 404是 base_url 或路径拼错了。第二步验证 MCP 服务器能启动。在终端里手动跑一次cd /absolute/path/to/blender-mcp uv run src/blender_mcp/server.py成功的话会看到服务器启动日志没有报错就说明依赖和配置都加载正常。如果报模块找不到检查 uv 的虚拟环境是否创建成功。第三步端到端验证。先在 Blender 里打开 BlenderMCP 标签页点 Connect to Claude确保终端里 MCP 服务器在运行。然后在客户端里发一条测试指令比如「创建一个球体并放在立方体上方」。成功的话 Blender 视图里会实时出现对象客户端会返回执行结果。这一步跑通整条链路就闭环了。提示验证阶段建议用最简单的指令不要一上来就让它生成复杂场景。简单指令能快速定位是链路问题还是模型理解问题。5. 常见报错排查接入过程中有几类报错反复出现这里按现象、原因、解决三步列出来。报错一Connection refused端口 9876 连不上。现象是 MCP 服务器日志里反复出现 socket 连接失败。原因是 Blender 插件没启动或者插件里的端口和 config.toml 里写的不一致。解决方法是回到 Blender确认 BlenderMCP 标签页里显示的是 Connected 状态端口号两边对齐。如果 Blender 重启过插件需要重新点一次 Connect。报错二401 Unauthorized。现象是模型调用直接失败日志里能看到认证错误。原因是 Key 没注入成功或者.env没被加载。检查settings.json的 env 段里 Key 是否正确以及环境变量名是否和 config.toml 里的${TAOTOKEN_API_KEY}完全一致。大小写敏感别写错。报错三模型返回的 Python 代码执行报错。现象是 Blender 里弹出 Python traceback。原因是模型生成的代码用了当前 Blender 版本不支持的 API或者对象引用不存在。解决方法是把复杂指令拆成多个小步骤先创建对象再改属性不要一步到位。另外可以在 config.toml 里把 temperature 再调低减少模型自由发挥。报错四uv 启动超时。现象是客户端启动 MCP 服务器时卡住。原因是 uv 第一次运行要下载依赖网络慢就会超时。解决方法是先在终端里手动跑一次uv run把依赖缓存好之后客户端启动就快了。报错五Blender 插件加载失败。现象是 Add-ons 里勾选后报错。原因是 Blender 版本低于 3.0或者 addon.py 文件损坏。确认版本后重新下载插件文件安装前先禁用再重新启用。6. 把通道固定下来后续只改模型名整套配置跑通后你会发现日常使用中真正需要动的只有一个字段model_name。Key 和 base_url 固定走 TaoToken 的统一通道Blender 连接参数固定MCP 服务器注册信息固定。这意味着你可以在不同模型之间快速切换做对比而不用每次重配一遍环境。如果你主要做长期编码和 Agent 类任务建议把模型调用额度规划一下Coding Plan 适合这种持续调用的场景。需要管理多个 Key 或查看调用量去控制台。想先快速试一下模型对话效果可以直接用模型对话页面。接入文档里有完整的参数说明和更多客户端配置示例遇到本文没覆盖的报错可以去那里对照排查。最后留一个实用习惯每次改完配置先跑第 4 节的第一步 curl 验证再跑端到端验证。两步都过再开始正式用能省掉大量「以为是模型问题其实是配置问题」的排查时间。