Blender3.0及以上版本推荐4.0稳定性更佳Cursor最新正式版已内置MCP协议支持无需额外安装插件用别的 trae、claude code、codex也是一样的仅配置mcp步骤略有区别Python3.10及以上版本Windows/Mac系统一般预装可在终端输入python --version校验网络环境能正常访问GitHub无特殊网络限制若有网络问题可提前配置好终端代理二、核心第一步安装并配置uv包管理器这是整个部署流程最关键、最优先执行的步骤。blender-mcp的运行完全依赖uvx命令而uvx是uv包管理器内置的工具必须先完成uv的安装和环境配置。2.1 安装uv根据你的操作系统在对应终端执行安装命令Windows系统以管理员身份打开PowerShell右键开始菜单→Windows PowerShell(管理员)复制以下命令回车执行powershell -c irm https://astral.sh/uv/install.ps1 | iex等待执行完成终端出现安装成功提示即完成uv的安装。Mac系统打开终端直接执行brew安装命令brew install uv等待brew执行完成无报错即安装成功。安装之后可以用以下命令检测是否成功正确安装2.2 配置环境变量Windows必做Mac可选Windows系统安装完成后需要手动将uv的安装目录添加到系统环境变量否则终端会提示「uvx不是内部或外部命令」打开PowerShell依次执行以下2行命令永久添加环境变量$localBin $env:USERPROFILE\.local\bin $userPath [Environment]::GetEnvironmentVariable(Path, User) [Environment]::SetEnvironmentVariable(Path, $userPath;$localBin, User)执行完成后重启PowerShell/终端让环境变量生效。2.3 验证安装是否成功重启终端后执行以下命令校验uv和uvx是否正常工作uv --version uvx --version若终端输出版本号无报错即说明核心依赖安装完成若仍提示命令不存在重启电脑后再次校验即可。三、第二步Blender端安装与配置blender-mcp插件3.1 下载插件核心文件blender-mcp的插件核心是addon.py文件有2种获取方式任选其一即可方式一git克隆推荐方便后续更新打开终端进入你想存放项目的目录执行git克隆命令git clone https://github.com/ahujasid/blender-mcp.git克隆完成后打开文件夹即可在根目录找到addon.py文件。方式二直接下载单个文件打开blender-mcp的GitHub仓库GitHub - ahujasid/blender-mcp: Open-source MCP to use Blender with any LLM · GitHub按照以上步骤下载压缩包之后并解压确保解压之后文件夹如下所示注意若你之前安装过旧版blender-mcp需先在Blender中禁用并卸载旧版插件再安装新版避免冲突。3.2 Blender内安装插件打开你的Blender软件点击顶部菜单栏的「编辑(Edit)」→「偏好设置(Preferences)」。在弹出的偏好设置窗口中左侧切换到「插件(Add-ons)」选项卡。点击窗口右上角的「安装(Install...)」按钮在文件浏览器中选择你刚才下载的addon.py文件点击「安装插件(Install Add-on)」。安装完成后在插件列表中搜索「Blender MCP」会找到名为「Interface: Blender MCP」的插件勾选插件前方的复选框启用插件。3.3 验证插件加载成功启用插件后关闭偏好设置窗口回到Blender的3D视图界面按下键盘上的N键调出3D视图的右侧侧边栏。在侧边栏的标签中找到「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服务无需重复配置。打开Cursor编辑器点击左下角的设置图标打开设置面板。在设置面板的左侧菜单中找到「MCP」选项点击进入MCP配置页面。点击页面中的「Add new global MCP server添加新的全局MCP服务器」按钮会弹出一个JSON配置编辑框。根据你的操作系统复制对应的配置代码粘贴到编辑框中点击保存系统配置{ mcpServers: { blender: { command: uvx, args: [blender-mcp] ] } } }保存配置后Cursor会自动加载该MCP服务若配置正确服务列表中会出现「blender」服即说明配置成功。4.2 方案二项目专属MCP配置若你只想在特定的Blender项目中使用该AI能力可选择项目专属配置在Cursor中打开你的Blender项目根目录。在项目根目录中创建一个名为.cursor的文件夹进入该文件夹新建一个名为mcp.json的文件。打开mcp.json文件根据你的系统粘贴上方4.1中对应的配置代码保存文件。重启Cursor重新打开该项目配置会自动生效可在设置的MCP页面中看到项目专属的服务。五、第四步Blender与Cursor双向连接与连通性测试完成以上所有配置后我们来完成最终的连接验证AI是否能正常操控Blender。5.1 Blender端启动MCP服务回到Blender软件确保已经启用了Blender MCP插件按下N键打开侧边栏进入「BlenderMCP」标签。确认端口为9876点击面板中的「Connect to Claude连接到MCP服务」按钮。按钮下方出现「Running on port 9876」的提示即说明Blender端的socket服务已成功启动正在等待Cursor的连接。5.2 Cursor端验证工具加载回到Cursor编辑器按刚才的方法进入MCP界面在工具列表中能看到「blender」分类点击右侧的打开以下状态就是对的5.3 最简连通性测试我们用一条最简单的指令验证AI是否能正常操控Blender在Cursor的对话输入框中输入以下指令发送给AI帮我在Blender场景中创建一个半径为2m的球体再创建一个边长为1m的立方体把立方体放在球体的正上方两者间距0.5m。发送后AI会自动调用Blender MCP工具向Blender发送操作指令。若Blender场景中瞬间出现了对应的球体和立方体位置完全符合要求即说明全流程部署成功若AI提示工具调用失败可查看下方的排错指南解决对应问题。六、常见问题与排错指南问题1终端提示「uvx不是内部或外部命令」原因uv的安装目录未添加到系统环境变量或环境变量未生效。解决方案重新执行本文2.2中的环境变量配置命令确保命令执行无报错。重启终端甚至重启电脑让环境变量彻底生效。Windows用户可手动打开环境变量编辑器在用户变量的Path中手动添加C:\Users\你的用户名\.local\bin保存后重启电脑。问题2Cursor中MCP服务显示红色报错无法加载原因配置文件格式错误、uvx命令不可用、网络问题导致blender-mcp包下载失败。解决方案检查JSON配置文件确保括号、引号完全闭合无语法错误Windows和Mac的配置不要混用。手动在终端执行uvx blender-mcp若终端无报错说明包可正常运行若报错执行uvx --force blender-mcp强制重新安装包。检查网络环境确保能正常访问PyPI源可切换国内PyPI镜像后重试。问题3AI发送指令后Blender无任何反应原因Blender端服务未启动、端口不匹配、防火墙拦截、多个MCP服务同时运行。解决方案确认Blender端已点击「Connect to Claude」且提示服务正在运行端口号和配置文件中一致。关闭Windows防火墙/系统防火墙的拦截或给9876端口添加防火墙白名单。关闭Claude、VS Code等其他客户端的blender-mcp服务只保留Cursor中的一个服务运行。重启Blender和Cursor重新启动服务后重试。问题4Blender中启用插件后侧边栏看不到BlenderMCP标签原因Blender版本不兼容、插件安装失败、Python环境缺失。解决方案确认Blender版本≥3.0低于该版本请升级Blender。重新下载addon.py文件确保文件下载完整无损坏重新安装插件。打开Blender的「脚本」工作区查看控制台是否有报错根据报错信息排查问题多数为Python依赖缺失可手动安装对应依赖。七、实战上手即用型AI建模Prompt示例部署成功后你可以用这些Prompt快速上手体验AI驱动3D创作的能力也可以根据自己的需求修改扩展基础场景建模帮我在Blender中创建一个低多边形的森林小场景包含5棵不同形态的松树、一个小木屋、一圈木栅栏地面做草地材质整体风格统一面数控制在1万面以内。Cursor界面Blender界面材质与渲染调整帮我把场景中的立方体换成红色的金属材质粗糙度0.1金属度0.9再给场景添加3点布光主光强度2补光强度0.5背光强度0.3渲染器切换为Cycles采样数设置为128。Cursor界面Blender界面
Blender3.0及以上版本推荐4.0稳定性更佳Cursor最新正式版已内置MCP协议支持无需额外安装插件用别的 trae、claude code、codex也是一样的仅配置mcp步骤略有区别Python3.10及以上版本Windows/Mac系统一般预装可在终端输入python --version校验网络环境能正常访问GitHub无特殊网络限制若有网络问题可提前配置好终端代理二、核心第一步安装并配置uv包管理器这是整个部署流程最关键、最优先执行的步骤。blender-mcp的运行完全依赖uvx命令而uvx是uv包管理器内置的工具必须先完成uv的安装和环境配置。2.1 安装uv根据你的操作系统在对应终端执行安装命令Windows系统以管理员身份打开PowerShell右键开始菜单→Windows PowerShell(管理员)复制以下命令回车执行powershell -c irm https://astral.sh/uv/install.ps1 | iex等待执行完成终端出现安装成功提示即完成uv的安装。Mac系统打开终端直接执行brew安装命令brew install uv等待brew执行完成无报错即安装成功。安装之后可以用以下命令检测是否成功正确安装2.2 配置环境变量Windows必做Mac可选Windows系统安装完成后需要手动将uv的安装目录添加到系统环境变量否则终端会提示「uvx不是内部或外部命令」打开PowerShell依次执行以下2行命令永久添加环境变量$localBin $env:USERPROFILE\.local\bin $userPath [Environment]::GetEnvironmentVariable(Path, User) [Environment]::SetEnvironmentVariable(Path, $userPath;$localBin, User)执行完成后重启PowerShell/终端让环境变量生效。2.3 验证安装是否成功重启终端后执行以下命令校验uv和uvx是否正常工作uv --version uvx --version若终端输出版本号无报错即说明核心依赖安装完成若仍提示命令不存在重启电脑后再次校验即可。三、第二步Blender端安装与配置blender-mcp插件3.1 下载插件核心文件blender-mcp的插件核心是addon.py文件有2种获取方式任选其一即可方式一git克隆推荐方便后续更新打开终端进入你想存放项目的目录执行git克隆命令git clone https://github.com/ahujasid/blender-mcp.git克隆完成后打开文件夹即可在根目录找到addon.py文件。方式二直接下载单个文件打开blender-mcp的GitHub仓库GitHub - ahujasid/blender-mcp: Open-source MCP to use Blender with any LLM · GitHub按照以上步骤下载压缩包之后并解压确保解压之后文件夹如下所示注意若你之前安装过旧版blender-mcp需先在Blender中禁用并卸载旧版插件再安装新版避免冲突。3.2 Blender内安装插件打开你的Blender软件点击顶部菜单栏的「编辑(Edit)」→「偏好设置(Preferences)」。在弹出的偏好设置窗口中左侧切换到「插件(Add-ons)」选项卡。点击窗口右上角的「安装(Install...)」按钮在文件浏览器中选择你刚才下载的addon.py文件点击「安装插件(Install Add-on)」。安装完成后在插件列表中搜索「Blender MCP」会找到名为「Interface: Blender MCP」的插件勾选插件前方的复选框启用插件。3.3 验证插件加载成功启用插件后关闭偏好设置窗口回到Blender的3D视图界面按下键盘上的N键调出3D视图的右侧侧边栏。在侧边栏的标签中找到「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服务无需重复配置。打开Cursor编辑器点击左下角的设置图标打开设置面板。在设置面板的左侧菜单中找到「MCP」选项点击进入MCP配置页面。点击页面中的「Add new global MCP server添加新的全局MCP服务器」按钮会弹出一个JSON配置编辑框。根据你的操作系统复制对应的配置代码粘贴到编辑框中点击保存系统配置{ mcpServers: { blender: { command: uvx, args: [blender-mcp] ] } } }保存配置后Cursor会自动加载该MCP服务若配置正确服务列表中会出现「blender」服即说明配置成功。4.2 方案二项目专属MCP配置若你只想在特定的Blender项目中使用该AI能力可选择项目专属配置在Cursor中打开你的Blender项目根目录。在项目根目录中创建一个名为.cursor的文件夹进入该文件夹新建一个名为mcp.json的文件。打开mcp.json文件根据你的系统粘贴上方4.1中对应的配置代码保存文件。重启Cursor重新打开该项目配置会自动生效可在设置的MCP页面中看到项目专属的服务。五、第四步Blender与Cursor双向连接与连通性测试完成以上所有配置后我们来完成最终的连接验证AI是否能正常操控Blender。5.1 Blender端启动MCP服务回到Blender软件确保已经启用了Blender MCP插件按下N键打开侧边栏进入「BlenderMCP」标签。确认端口为9876点击面板中的「Connect to Claude连接到MCP服务」按钮。按钮下方出现「Running on port 9876」的提示即说明Blender端的socket服务已成功启动正在等待Cursor的连接。5.2 Cursor端验证工具加载回到Cursor编辑器按刚才的方法进入MCP界面在工具列表中能看到「blender」分类点击右侧的打开以下状态就是对的5.3 最简连通性测试我们用一条最简单的指令验证AI是否能正常操控Blender在Cursor的对话输入框中输入以下指令发送给AI帮我在Blender场景中创建一个半径为2m的球体再创建一个边长为1m的立方体把立方体放在球体的正上方两者间距0.5m。发送后AI会自动调用Blender MCP工具向Blender发送操作指令。若Blender场景中瞬间出现了对应的球体和立方体位置完全符合要求即说明全流程部署成功若AI提示工具调用失败可查看下方的排错指南解决对应问题。六、常见问题与排错指南问题1终端提示「uvx不是内部或外部命令」原因uv的安装目录未添加到系统环境变量或环境变量未生效。解决方案重新执行本文2.2中的环境变量配置命令确保命令执行无报错。重启终端甚至重启电脑让环境变量彻底生效。Windows用户可手动打开环境变量编辑器在用户变量的Path中手动添加C:\Users\你的用户名\.local\bin保存后重启电脑。问题2Cursor中MCP服务显示红色报错无法加载原因配置文件格式错误、uvx命令不可用、网络问题导致blender-mcp包下载失败。解决方案检查JSON配置文件确保括号、引号完全闭合无语法错误Windows和Mac的配置不要混用。手动在终端执行uvx blender-mcp若终端无报错说明包可正常运行若报错执行uvx --force blender-mcp强制重新安装包。检查网络环境确保能正常访问PyPI源可切换国内PyPI镜像后重试。问题3AI发送指令后Blender无任何反应原因Blender端服务未启动、端口不匹配、防火墙拦截、多个MCP服务同时运行。解决方案确认Blender端已点击「Connect to Claude」且提示服务正在运行端口号和配置文件中一致。关闭Windows防火墙/系统防火墙的拦截或给9876端口添加防火墙白名单。关闭Claude、VS Code等其他客户端的blender-mcp服务只保留Cursor中的一个服务运行。重启Blender和Cursor重新启动服务后重试。问题4Blender中启用插件后侧边栏看不到BlenderMCP标签原因Blender版本不兼容、插件安装失败、Python环境缺失。解决方案确认Blender版本≥3.0低于该版本请升级Blender。重新下载addon.py文件确保文件下载完整无损坏重新安装插件。打开Blender的「脚本」工作区查看控制台是否有报错根据报错信息排查问题多数为Python依赖缺失可手动安装对应依赖。七、实战上手即用型AI建模Prompt示例部署成功后你可以用这些Prompt快速上手体验AI驱动3D创作的能力也可以根据自己的需求修改扩展基础场景建模帮我在Blender中创建一个低多边形的森林小场景包含5棵不同形态的松树、一个小木屋、一圈木栅栏地面做草地材质整体风格统一面数控制在1万面以内。Cursor界面Blender界面材质与渲染调整帮我把场景中的立方体换成红色的金属材质粗糙度0.1金属度0.9再给场景添加3点布光主光强度2补光强度0.5背光强度0.3渲染器切换为Cycles采样数设置为128。Cursor界面Blender界面
