1. 为什么要在 Cursor 里接上 Blender：一个真实卡了三天的场景

先说清楚这套东西是什么。Blender MCP 是一个把 Blender 变成 MCP Server 的开源项目，它让 Cursor 这类支持 MCP 协议的编辑器，能通过自然语言直接驱动 Blender 建模。你打一句「创建一个球体并给它加个金属材质」，Cursor 会生成对应的 Python 脚本，再通过 MCP 通道把指令送进 Blender 执行。适合谁？适合做 3D 建模、场景搭建、批量资产处理，又不想每次都手写 bpy 脚本的人。

我最初的想法很简单：Cursor 写代码强，Blender 的 Python API 又全，那让 Cursor 直接控制 Blender 不就完了。结果从装 uv 到 mcp.json 配好，中间踩了三个坑——后台模式 GPU 报错、模块找不到、Cursor 里 MCP 一直红灯。这篇文章就是把这条链路完整走一遍，包括把 API 通道统一到 TaoToken 之后的连通性验证，让你少走弯路。

整条链路分四层：Blender 端跑 MCP Server（blender-mcp），Cursor 端通过 mcp.json 声明这个 Server，Cursor 的 Agent 生成 Python 代码，代码经 MCP 通道在 Blender 里执行。任何一层断了，表现都是「Cursor 里点了 Run 但 Blender 没反应」。所以排查的核心思路是：先确认 Blender 端 Server 活着，再确认 Cursor 读到了配置，最后确认指令真的送达了。

下面按「装后端 → 配 mcp.json → 写启动脚本 → 验证 → 排错」的顺序来，每一步都给可复制的命令和配置。

2. 前置准备：Blender、Python、uv 与 TaoToken 统一 Key 接入

2.1 环境清单

先把要装的东西列清楚，版本不对后面全是坑：

Blender 从官网下载安装即可，安装路径记下来，后面启动脚本要用。Python 建议单独装一个 3.10 或 3.11，别用 Blender 自带的那个，避免路径混乱。

2.2 安装 uv

uv 是启动 blender-mcp 的关键，它负责把包拉下来并以 uvx 方式运行。Windows 下用 PowerShell 装：

powershell -Command "irm https://astral.sh/uv/install.ps1 | iex"

如果 PowerShell 的 TLS 版本或执行策略拦住了，别硬刚，手动下载 install_uv.ps1 脚本，然后临时绕过执行策略运行，不改系统默认设置：

powershell -ExecutionPolicy Bypass -File .\install_uv.ps1

装完验证一下：

uv --version uvx --version

两个都能打印版本号，说明工具链就绪。

2.3 把 API 通道统一到 TaoToken

这一步是很多人忽略的。Cursor 在生成 Blender 控制脚本时，背后是要调模型的。如果你用的是默认通道，额度、稳定性、计费都分散在各处。把通道统一到 TaoToken 之后，Cursor 侧只需要一个 Key，模型调用走同一个入口，排查问题时也少一个变量。

TaoToken 的接入信息：

• 官网：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API Base URL：https://taotoken.net/api
• 模型对话入口：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite
• API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite
• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

先去 API Keys 页面生成一个 Key，复制保存好。这个 Key 后面会同时用在 Cursor 的模型配置里。注意，Blender MCP 本身不调模型，它只负责把 Cursor 生成的代码送进 Blender；真正调模型的是 Cursor。所以 TaoToken 的 Key 是配在 Cursor 的模型设置里，不是配在 mcp.json 里。这一点很多人搞混，导致 mcp.json 里塞了 Key 却一直连不上。

2.4 下载 blender-mcp 项目

从项目仓库下载或克隆 blender-mcp，解压到一个固定目录，比如：

F:/_Software/Blender 4.1/blender-mcp-main

后端主脚本在：

F:/_Software/Blender 4.1/blender-mcp-main/src/blender_mcp/server.py

记住这个路径，启动脚本和排错都要用。

3. 可复制配置：mcp.json 与 Cursor 侧完整设置

3.1 mcp.json 放哪、写什么

Cursor 的 MCP 配置文件默认在：

C:\Users\Administrator\.cursor\mcp.json

注意把 Administrator 换成你自己的 Windows 用户名。这个文件如果不存在就新建一个。写入以下内容：

{ "mcpServers": { "blender": { "command": "cmd", "args": [ "/c", "uvx", "blender-mcp" ] } } }

这段配置的意思是：Cursor 启动时，用 cmd 调 uvx 拉起 blender-mcp 这个 Server。command 用 cmd 是为了在 Windows 下能正确解析 uvx 的路径。如果你把 uvx 装在了非默认位置，这里可能要写全路径。

3.2 Cursor 侧模型通道配置

mcp.json 只管 MCP Server，模型通道在 Cursor 的设置里单独配。打开 Cursor 设置，找到模型相关配置，把 Base URL 指向 TaoToken：

Base URL: https://taotoken.net/api API Key: 你刚才生成的 TaoToken Key Model ID: 按接入文档里支持的模型名填写

这三件套（Base URL + Key + Model ID）缺一不可。Base URL 末尾不要多加斜杠，Model ID 要和文档里列出的完全一致，大小写都别错。配完保存，Cursor 会用它来生成 Blender 控制脚本。

3.3 启动脚本：Blender_MCP_Server_Start.bat

手动敲命令太累，写个批处理。新建文本文件，粘贴以下内容，保存为 Blender_MCP_Server_Start.bat：

@echo off title Blender MCP Server Launcher echo 正在启动 Blender MCP Server... cd /d "F:/_Software/Blender 4.1/blender-mcp-main/src" "F:/_Software/Blender 4.1/blender.exe" --background --factory-startup --python blender_mcp/server.py pause

几个关键点：

• cd /d切到项目 src 目录，这是为了让 Python 能找到 mcp 模块，路径不对就会报 ModuleNotFoundError。
• --background让 Blender 后台运行，不弹界面。
• --factory-startup是关键，它禁用用户配置的插件，避免后台模式下加载 HOps 之类的插件导致 GPU API 报错。
• pause让窗口停住，方便看日志。

把脚本里的两个路径换成你自己的实际路径。

3.4 目录结构对照

配好之后，你的目录大概长这样：

F:/_Software/Blender 4.1/ ├── blender.exe └── blender-mcp-main/ └── src/ └── blender_mcp/ └── server.py

启动脚本里的 cd 指向 src，python 参数指向 server.py，两者要对得上。

4. 验证请求：从启动到 Cursor 里创建第一个球体

4.1 启动后端

双击 Blender_MCP_Server_Start.bat。命令行窗口会打印启动日志，看到类似「MCP Server 启动成功」「监听中」的信息就对了。如果窗口一闪而过，说明脚本里某条命令失败了，把 pause 保留着就能看到报错。

4.2 确认 Cursor 读到配置

打开 Cursor，进入 MCP Servers 面板。正常情况下，blender 这一项应该显示绿灯，表示连接成功。如果显示红灯或灰色，先别急着改代码，回到第 5 节看排错。

4.3 下发第一条指令

在 Cursor 的聊天框里，直接打中文：

创建一个球体

Cursor 会生成一段 bpy 代码，类似：

import bpy bpy.ops.mesh.primitive_uv_sphere_add(radius=1, location=(0, 0, 0))

然后点 Run 按钮。如果一切正常，Blender 后台场景里就会多出一个球体。你可以再让它「把球体改成红色金属材质」，验证多步指令也能走通。

4.4 验证 API 通道

为了确认模型调用走的是 TaoToken，可以在 Cursor 里发一条稍复杂的指令，比如「创建一个立方体，然后复制三个，沿 X 轴等距排列」。这条指令需要模型理解并生成循环代码。如果生成正确且执行成功，说明 TaoToken 通道是通的。如果生成报错或超时，去 TaoToken 的 API Keys 页面看调用记录，确认请求确实打到了 https://taotoken.net/api。

4.5 关闭流程

用完先在后端命令行窗口按 Ctrl+C 终止服务，再关 Blender（后台模式下关窗口通常就退了），最后关 Cursor。顺序反了有时会留下僵尸进程占端口。

5. 常见报错排查：401、local proxy failed、reading choices 与 OAuth

这一节是重点，把真实会遇到的报错和定位方法列出来。

5.1 GPU API is not available in background mode

完整报错：

SystemError: GPU API is not available in background mode

原因：后台模式下加载了不适用的插件，典型的是 HOps。解决：启动 Blender 时加--factory-startup，禁用用户配置插件。启动脚本里已经带了，如果你手动启动，记得也加上。

5.2 ModuleNotFoundError: No module named 'mcp'

完整报错：

ModuleNotFoundError: No module named 'mcp'

原因：工作目录不对，Python 找不到 mcp 模块。两种解法。一是确保启动脚本里的cd /d指向正确的 src 目录。二是在 server.py 开头加路径修正：

import sys, os sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))

加完保存，重启后端。

5.3 401 Unauthorized

完整报错：

401 Unauthorized

这个报错出现在 Cursor 调模型时，不是 MCP 通道的问题。原因通常是 TaoToken 的 Key 没填、填错，或者 Base URL 写成了带斜杠的版本。检查三件套：Base URL 用https://taotoken.net/api，Key 从 API Keys 页面重新复制，Model ID 和文档一致。改完重启 Cursor。

5.4 local proxy failed

完整报错：

local proxy failed

这个一般出现在 Cursor 的网络配置层。先确认 Base URL 没写错，再确认本机没有其他网络工具干扰。把 Cursor 的模型配置重置成 TaoToken 的标准三件套，重启 Cursor 再试。如果还不行，去接入文档核对当前推荐的配置格式。

5.5 reading choices 相关报错

完整报错类似：

error reading choices

这通常是模型返回格式和 Cursor 预期不一致导致的，根源还是通道配置。确认 Model ID 是文档里明确支持的，别自己拼一个不存在的名字。换成文档推荐的模型再试。

5.6 OAuth 相关报错

如果看到 OAuth 字样，说明 Cursor 在尝试走某种授权流程，而 TaoToken 的接入是 Key 模式，不需要 OAuth。检查是不是在 Cursor 里误开了某个需要授权的模型源，把它关掉，回到 Key 模式。

5.7 MCP 一直红灯

如果 mcp.json 配好了但 Cursor 里 blender 一直红灯，按顺序查：uvx 能不能在命令行单独跑起来（uvx blender-mcp）；mcp.json 的 JSON 格式有没有语法错误（少逗号、多逗号都会挂）；Cursor 有没有重启（改完 mcp.json 必须重启才生效）。

6. 把这条链路用顺：CTA 与长期编码建议

走到这里，你应该已经能在 Cursor 里用中文指挥 Blender 建模了。回顾一下整条链路的关键节点：uv 装好、blender-mcp 下载到位、mcp.json 写对、启动脚本带--factory-startup、Cursor 侧三件套配到 TaoToken。任何一环出问题，表现都是「点了没反应」，所以排查时按层往下剥。

如果你打算长期用这套做 3D 资产或场景自动化，建议把模型通道固定下来，别今天换一个明天换一个。TaoToken 的 Coding Plan 适合这种长期编码和 Agent 场景，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。需要临时验证某个模型效果时，用模型对话页面快速试：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。Key 管理和文档分别在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 和 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

最后给个实用技巧：把常用的 Blender 操作写成 Cursor 里的自定义指令模板，比如「批量给选中物体加倒角」「按命名规则重命名场景对象」，这样每次不用重新描述，直接调用模板，效率会高很多。Blender MCP 的价值不在于替代你建模，而在于把重复的、规则化的操作交给自然语言去驱动。