本文针对已预装 Blender的用户，提供保姆级的blender-mcp插件部署全流程。通过这套方案，你可以直接在用自然语言操控Blender，实现AI自动建模、场景搭建、材质调整、灯光渲染等全流程3D创作，彻底释放AI在3D设计中的生产力。

前言

blender-mcp是基于Model Context Protocol（MCP协议） 开发的Blender AI集成插件，它能让支持MCP协议的AI客户端（Cursor、Claude等）直接与Blender建立双向通信，把大语言模型的代码能力和自然语言理解能力，转化为Blender里可执行的3D创作指令。

无需手动写Python脚本，一句自然语言，就能让AI帮你完成从基础建模到完整场景渲染的全流程操作。本文所有步骤均经过实测，跟着操作即可100%完成部署。

一、前置环境校验

在开始部署前，先确认你的环境满足最低要求，避免后续出现兼容性问题：

1. Blender：3.0及以上版本（推荐4.0+，稳定性更佳）
2. Cursor：最新正式版（已内置MCP协议支持，无需额外安装插件）（用别的 trae、claude code、codex也是一样的，仅配置mcp步骤略有区别）
3. Python：3.10及以上版本（Windows/Mac系统一般预装，可在终端输入python --version校验）
4. 网络环境：能正常访问GitHub，无特殊网络限制（若有网络问题，可提前配置好终端代理）

二、核心第一步：安装并配置uv包管理器

这是整个部署流程最关键、最优先执行的步骤。blender-mcp的运行完全依赖uvx命令，而uvx是uv包管理器内置的工具，必须先完成uv的安装和环境配置。

2.1 安装uv

根据你的操作系统，在对应终端执行安装命令：

• Windows系统：

1. 以管理员身份打开PowerShell（右键开始菜单→Windows PowerShell(管理员)）
2. 复制以下命令，回车执行：
3.    powershell

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

1. 等待执行完成，终端出现安装成功提示，即完成uv的安装。

• Mac系统：

1. 打开终端，直接执行brew安装命令：
2.    bash

brew install uv

1. 等待brew执行完成，无报错即安装成功。

安装之后可以用以下命令检测是否成功正确安装

2.2 配置环境变量（Windows必做，Mac可选）

Windows系统安装完成后，需要手动将uv的安装目录添加到系统环境变量，否则终端会提示「uvx不是内部或外部命令」：

1. 打开PowerShell，依次执行以下2行命令，永久添加环境变量：
2.    powershell

$localBin = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User")

1. 执行完成后，重启PowerShell/终端，让环境变量生效。

2.3 验证安装是否成功

重启终端后，执行以下命令，校验uv和uvx是否正常工作：

   bash

uv --version
uvx --version

若终端输出版本号，无报错，即说明核心依赖安装完成；若仍提示命令不存在，重启电脑后再次校验即可。

三、第二步：Blender端安装与配置blender-mcp插件

3.1 下载插件核心文件

blender-mcp的插件核心是addon.py文件，有2种获取方式，任选其一即可：

• 方式一：git克隆（推荐，方便后续更新）打开终端，进入你想存放项目的目录，执行git克隆命令：
•    bash

git clone https://github.com/ahujasid/blender-mcp.git

• 克隆完成后，打开文件夹，即可在根目录找到addon.py文件。
• 方式二：直接下载单个文件

1. 打开blender-mcp的GitHub仓库：https://github.com/ahujasid/blender-mcp 按照以上步骤下载压缩包之后并解压，确保解压之后文件夹如下所示

注意：若你之前安装过旧版blender-mcp，需先在Blender中禁用并卸载旧版插件，再安装新版，避免冲突。

3.2 Blender内安装插件

1. 打开你的Blender软件，点击顶部菜单栏的「编辑(Edit)」→「偏好设置(Preferences)」。
   
2. 在弹出的偏好设置窗口中，左侧切换到「插件(Add-ons)」选项卡。
   
3. 点击窗口右上角的「安装(Install…)」按钮，在文件浏览器中，选择你刚才下载的addon.py文件，点击「安装插件(Install Add-on)」。
   
4. 安装完成后，在插件列表中，搜索「Blender MCP」，会找到名为「Interface: Blender MCP」的插件，勾选插件前方的复选框，启用插件。
   

3.3 验证插件加载成功

启用插件后，关闭偏好设置窗口，回到Blender的3D视图界面：

1. 按下键盘上的N键，调出3D视图的右侧侧边栏。
2. 在侧边栏的标签中，找到「BlenderMCP」标签，点击进入，若能看到插件的控制面板（包含端口设置、连接按钮、资产开关等），即说明插件安装成功。

### 3.4 插件基础配置

插件面板中可提前完成全部基础配置，一次设置长期生效，后续使用无需重复调整，各项配置详细说明如下：

• 端口(Port)：为Blender插件与MCP后端服务通信的本地TCP端口，相当于两者互联的专属通道。默认固定为9876，常规使用无需修改；仅在端口被其他软件占用时更换端口，必须保证插件端口与MCP服务端口完全一致，端口不匹配会导致连接失败、AI功能全部失效。
• Poly Haven资产：Poly Haven为免费开源3D资源平台，包含模型、材质、HDRI环境贴图等素材。勾选对应复选框后，AI可自动联网下载并调用该平台资源，快速搭建完整场景；无需外部资源自动加载时可不开启，属于可选配置，关闭不影响插件核心功能。
• Sketchfab资产：全球大型3D模型共享平台，拥有海量免费及付费三维资源。开启该选项可允许插件调用平台模型，需填写专属API Key完成权限认证，否则会出现访问限制、调用失败问题，适合需要快速调取特色模型的使用场景。
• Hyper3D Rodin AI生成服务：云端3D生成工具，支持通过文字描述快速生成三维模型。开启后可接入官方云端API，搭配专属API密钥解锁使用额度，同时支持一键申领免费试用密钥，快速启用AI建模能力。
• 腾讯混元3D生成服务：独立的AI三维生成方案，可与Hyper3D服务并行启用。支持本地API部署与云端接入两种模式，填写对应服务地址即可使用；本地部署版本无需联网、响应更快，无云端额度限制，兼顾隐私与批量创作需求。
• 八叉树分辨率(Octree Resolution)：控制AI生成模型的体素精度，决定模型细节丰富度与整体面数。数值越高模型细节越精致，硬件消耗与生成时长越高；数值越低生成速度越快、模型轻量化，适合快速预览，默认256为均衡参数。
• 推理步数(Number of Inference Steps)：AI建模的迭代打磨次数。步数越高，模型造型越规整、瑕疵越少；步数越低生成效率越快，容易出现模型破损、造型扭曲等问题，可根据画质需求灵活调整。
• 引导系数(Guidance Scale)：用于平衡AI生成内容与文字描述的贴合度。数值偏高时，生成效果严格遵循提示词要求；数值偏低时AI创作自由度更高，风格更随机，合理参数可避免模型生硬或偏离需求。
• 生成纹理(Generate Texture)：控制AI是否同步输出模型材质与纹理贴图。关闭后仅生成纯白模型，运行速度快、性能压力小；开启后自动搭配色彩、法线等材质贴图，一键产出成品模型，耗时与硬件占用会相应增加。
• 断开MCP服务器连接：手动切断插件与MCP后端的通信连接，一键停用所有AI生成、资源调用功能。多用于重启服务、临时关闭AI功能的场景。
• 端口运行状态提示：实时显示插件当前监听运行的端口，用于快速核对端口配置是否正常，直观确认插件通信服务是否成功启动。
• 遥测设置：用于收集插件匿名使用数据，辅助开发者优化迭代。若注重隐私、拒绝数据上传，可在插件偏好设置内取消遥测同意勾选，关闭后不影响插件所有核心使用功能，为可选配置。

四、第三步：Agent 端MCP服务配置

这一步是建立和Blender通信的核心，我们提供全局MCP配置（推荐） 和项目专属配置两种方案，任选其一即可。这边我们以Cursor为例

重要提醒：不要同时在多个客户端（Claude、Cursor等）运行同一个blender-mcp服务，否则会出现端口占用、连接失败的问题。

4.1 方案一：全局MCP服务器配置（推荐）

全局配置完成后，你在Cursor中打开的所有项目，都可以直接使用Blender MCP服务，无需重复配置。

1. 打开Cursor编辑器，点击左下角的设置图标，打开设置面板。
   
2. 在设置面板的左侧菜单中，找到「MCP」选项，点击进入MCP配置页面。
   
3. 点击页面中的「Add new global MCP server（添加新的全局MCP服务器）」按钮，会弹出一个JSON配置编辑框。
   
4. 根据你的操作系统，复制对应的配置代码，粘贴到编辑框中，点击保存：

• 系统配置：
•    json

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

5. 保存配置后，Cursor会自动加载该MCP服务，若配置正确，服务列表中会出现「blender」服，即说明配置成功。

4.2 方案二：项目专属MCP配置

若你只想在特定的Blender项目中使用该AI能力，可选择项目专属配置：

1. 在Cursor中打开你的Blender项目根目录。
2. 在项目根目录中，创建一个名为.cursor的文件夹，进入该文件夹，新建一个名为mcp.json的文件。
3. 打开mcp.json文件，根据你的系统，粘贴上方4.1中对应的配置代码，保存文件。
4. 重启Cursor，重新打开该项目，配置会自动生效，可在设置的MCP页面中看到项目专属的服务。

五、第四步：Blender与Cursor双向连接与连通性测试

完成以上所有配置后，我们来完成最终的连接，验证AI是否能正常操控Blender。

5.1 Blender端启动MCP服务

1. 回到Blender软件，确保已经启用了Blender MCP插件，按下N键打开侧边栏，进入「BlenderMCP」标签。
   
2. 确认端口为9876，点击面板中的「Connect to Claude（连接到MCP服务）」按钮。
   
3. 按钮下方出现「Running on port 9876」的提示，即说明Blender端的socket服务已成功启动，正在等待Cursor的连接。
   

5.2 Cursor端验证工具加载

1. 回到Cursor编辑器，按刚才的方法进入MCP界面
2. 在工具列表中，能看到「blender」分类，点击右侧的打开

以下状态就是对的：

5.3 最简连通性测试

我们用一条最简单的指令，验证AI是否能正常操控Blender： 在Cursor的对话输入框中，输入以下指令，发送给AI：

帮我在Blender场景中，创建一个半径为2m的球体，再创建一个边长为1m的立方体，把立方体放在球体的正上方，两者间距0.5m。

发送后，AI会自动调用Blender MCP工具，向Blender发送操作指令。

• 若Blender场景中，瞬间出现了对应的球体和立方体，位置完全符合要求，即说明全流程部署成功！
• 若AI提示工具调用失败，可查看下方的排错指南，解决对应问题。

六、常见问题与排错指南

问题1：终端提示「uvx不是内部或外部命令」

• 原因：uv的安装目录未添加到系统环境变量，或环境变量未生效。
• 解决方案：

1. 重新执行本文2.2中的环境变量配置命令，确保命令执行无报错。
2. 重启终端，甚至重启电脑，让环境变量彻底生效。
3. Windows用户可手动打开环境变量编辑器，在用户变量的Path中，手动添加C:\Users\你的用户名\.local\bin，保存后重启电脑。

问题2：Cursor中MCP服务显示红色报错，无法加载

• 原因：配置文件格式错误、uvx命令不可用、网络问题导致blender-mcp包下载失败。
• 解决方案：

1. 检查JSON配置文件，确保括号、引号完全闭合，无语法错误，Windows和Mac的配置不要混用。
2. 手动在终端执行uvx blender-mcp，若终端无报错，说明包可正常运行；若报错，执行uvx --force blender-mcp，强制重新安装包。
3. 检查网络环境，确保能正常访问PyPI源，可切换国内PyPI镜像后重试。

问题3：AI发送指令后，Blender无任何反应

• 原因：Blender端服务未启动、端口不匹配、防火墙拦截、多个MCP服务同时运行。
• 解决方案：

1. 确认Blender端已点击「Connect to Claude」，且提示服务正在运行，端口号和配置文件中一致。
2. 关闭Windows防火墙/系统防火墙的拦截，或给9876端口添加防火墙白名单。
3. 关闭Claude、VS Code等其他客户端的blender-mcp服务，只保留Cursor中的一个服务运行。
4. 重启Blender和Cursor，重新启动服务后重试。

问题4：Blender中启用插件后，侧边栏看不到BlenderMCP标签

• 原因：Blender版本不兼容、插件安装失败、Python环境缺失。
• 解决方案：

1. 确认Blender版本≥3.0，低于该版本请升级Blender。
2. 重新下载addon.py文件，确保文件下载完整，无损坏，重新安装插件。
3. 打开Blender的「脚本」工作区，查看控制台是否有报错，根据报错信息排查问题，多数为Python依赖缺失，可手动安装对应依赖。

七、实战上手：即用型AI建模Prompt示例

部署成功后，你可以用这些Prompt快速上手，体验AI驱动3D创作的能力，也可以根据自己的需求修改扩展：

1. 基础场景建模

帮我在Blender中创建一个低多边形的森林小场景，包含5棵不同形态的松树、一个小木屋、一圈木栅栏，地面做草地材质，整体风格统一，面数控制在1万面以内。

Cursor界面：

Blender界面：

2. 材质与渲染调整

帮我把场景中的立方体，换成红色的金属材质，粗糙度0.1，金属度0.9，再给场景添加3点布光，主光强度2，补光强度0.5，背光强度0.3，渲染器切换为Cycles，采样数设置为128。

Cursor界面：

Blender界面：

3. 资产与场景搭建

帮我从Poly Haven下载一个适合海边的HDRI环境贴图，应用到场景中，再下载一个岩石模型和3个不同的海草模型，摆放在场景的前景位置，做出海边礁石的效果。

Cursor界面：

Blender界面：

4. 动画与基础关键帧

在场景中创造一个球体，做一个上下弹跳的循环动画，总时长100帧，弹跳高度3m，在第0帧、50帧、100帧分别设置关键帧，再给相机设置一个缓慢环绕的动画，始终对准球体。

Cursor界面：

Blender界面：

5. 场景信息与修改

先获取当前Blender场景的所有物体信息，列出每个物体的名称、面数、位置和材质，然后把所有物体，统一缩放为原来的3倍。

Cursor界面：

Prompt书写技巧：指令越具体，AI的执行效果越好；复杂场景建议拆分成多个步骤，分多次发送指令，避免单次指令太复杂导致超时或执行失败。

八、总结与进阶玩法

部署总结

整个部署流程核心只有4步：安装uv包管理器 → Blender安装addon插件 → Cursor配置MCP服务 → 启动连接并测试。只要严格按照步骤操作，就能在10分钟内完成整个部署，让你的Blender拥有AI原生创作能力。

进阶玩法

1. AI模型生成集成：插件已支持Hyper3D、混元3D等AI生成模型，可在配置中添加自己的API密钥，直接用文生3D模型，导入到Blender场景中。
2. 远程部署：可将blender-mcp服务部署在远程服务器上，修改BLENDER_HOST和BLENDER_PORT环境变量，实现远程操控Blender。
3. 自定义工具扩展：可基于blender-mcp的开源代码，添加自己需要的Blender操作工具，定制专属的AI建模能力。
4. 多智能体协作：在Cursor中配置多个MCP服务，让AI同时操控Blender、Figma、文件系统等工具，实现从设计到3D建模的全流程AI自动化。