BlenderMCP 配置指南从接入到排错的完整实战【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcpBlenderMCP 跑通之后你在 AI 客户端里敲一句话它就能在 Blender 里建物体、调材质、截视口图甚至执行任意 Python 代码——你说它动手。这篇文章只解决一件事把这套 BlenderMCP 配置从空白做到跑通并给你一张出问题能直接查的故障速查表。系统分两半跑在电脑上的 MCP 服务端进程负责跟大模型对话和住在 Blender 里的插件负责真正动手建模两边靠一条 TCP 套接字默认端口 9876交换指令与结果。适合不想手动点几百次菜单的建模师、想用 AI 加速原型的工作流控以及所有被连接超时spawn uvx ENOENT卡住过的人。接入前准备依赖清单与客户端选型这一节把硬件条件和入口先定下来避免装到一半发现环境不满足返工。最低依赖清单组件要求备注Blender3.0推荐 4.x / 5.x必须是带界面的正常会话blender -b后台模式跑不了命令Python3.10服务端由 uv 托管一般不用你操心uv最新版服务端的启动器兼包管理器装完要用uvx命令# macOS brew install uv # Linux curl -LsSf https://astral.sh/uv/install.sh | shWindows 在 PowerShell 里执行powershell -c irm https://astral.sh/uv/install.ps1 | iex⚠️ 两个容易翻车的点一是别用pip install uv凑合它经常不生成uvx命令二是 Windows 装完要把%USERPROFILE%\.local\bin加进 PATH 并重启终端。最后用uvx --version验证一下有输出才算装好。三种客户端选型对比选哪条路接入决定了后面配置写法和会不会踩 Windows 的坑客户端需要什么条件特点Claude 桌面版claude_desktop_config.json里一段 JSON最标准的入口macOS / Linux 开箱即用Cursor同样的 MCP JSON 配置Windows 上需要借cmd绕一道见下文Claude Code CLI不用配置文件终端里一行命令完成注册适合纯命令行工作流BlenderMCP 安装与第一条指令四步接通这一节按配客户端 → 装插件 → 连接 → 说话的顺序一次讲完跑完你手里就是一个能对话的 Blender。第 1 步客户端指向 blender-mcp。以 Claude 桌面版为例进设置 开发者 编辑配置往claude_desktop_config.json里贴{ mcpServers: { blender: { command: uvx, args: [blender-mcp] } } }含义就一句让 Claude 启动时通过uvx拉起名为blender-mcp的服务。贴完把客户端完全退出再重开它才会重新读配置。第 2 步把插件装进 Blender。从仓库根目录拿addon.py整个插件就这一个文件编辑 偏好设置 插件 安装…选中它然后在列表里勾选启用Interface: Blender MCP。第 3 步点 Connect。在 3D 视图按N唤出侧边栏切到BlenderMCP标签点Connect to Claude。侧边栏状态显示运行中说明插件端就绪回到 Claude工具列表里出现锤子图标代表 Blender 工具已挂上。第 4 步说出第一句话。发一句具体的指令比如建一个等轴视角的小房间灰色地板、三根白色方柱后墙中间放一扇木门。 第一条指令偶尔没反应别慌——首次 socket 握手容易丢一次包原样再发一遍通常就通了。接着一句别停追加截个视口图确认一下刚才建出来的东西。这一步会让 AI 真的看到场景它基于截图自查哪不对你直接说把木门往左挪半个柱距它再去修。这样操作 → 截图验证 → 修正的闭环就形成了比让它盲改可靠得多。BlenderMCP 配置详解总表与三类部署环境这一节把所有可动参数集中起来。如果你只是标准单机接入看懂总表前几行就够其余环境按需取用。总配置表配置项所在位置默认值什么时候改BLENDER_HOST服务端环境变量localhostBlender 跑在容器 / 远程机器时改成 MCP 进程够得着的地址BLENDER_PORT服务端环境变量9876端口被占用时换号比如9877插件端 Port 属性Blender 侧边栏输入框9876跟BLENDER_PORT走两边必须一致BLENDER_MCP_DISABLE_TELEMETRY环境变量未设置匿名统计开启设成true彻底关闭也可在插件偏好里取消遥测勾选UV_PYTHON_PREFERENCE环境变量未设置机器上有 conda / pyenv 时设only-managed让 uv 用自管 Python端口一致性是最常见的隐形 bug服务端和插件各记一份端口一个 9876 一个 9877连接就永远握不上手。改完任何一边把另一边的值核对一遍。标准接入Claude 桌面版 / 命令行 CLI上面第 1 步的 JSON 就是标准答案。如果机器上 conda 或 pyenv 的 Python 版本打架给服务端钉一个干净的 3.11args: [--python, 3.11, blender-mcp], env: { UV_PYTHON_PREFERENCE: only-managed }Claude Code CLI 也算一种客户端只是不用配置文件终端里一行注册完事claude mcp add blender uvx blender-mcp等价的手动方式是自己在终端写好环境变量再拉起进程export BLENDER_HOSTlocalhost export BLENDER_PORT9876 export BLENDER_MCP_DISABLE_TELEMETRYtrue uvx blender-mcp⚠️ 别把uvx blender-mcp手动挂成长驻进程。它应该由 MCP 客户端在后台拉起你在终端手跑会看到它卡住半天没输出——那不是死机是它在安静等客户端连进来按Ctrl-C退出即可。完全不想用 uv 的话pipx install blender-mcp效果等价。Windows 与图形界面客户端Windows 的 GUI 程序不继承终端 PATHuvx经常被找不到让cmd先出场再执行command: cmd, args: [/c, uvx, blender-mcp]另一条路是写绝对路径where uvx查出来的完整路径直接填进command。macOS 和 Linux 的 Cursor 用户不需要这步直接用uvx那版。Apple Silicon 上如果uvx试图编 x86_64 的包常见于 cryptography 编译报错强制 arm64 解释器args: [--python, 3.11-aarch64, blender-mcp]。容器 / WSL / 远程主机原则一句话Blender 必须监听在 MCP 进程够得着的地方。在客户端配置里加一段envenv: { BLENDER_HOST: host.docker.internal, BLENDER_PORT: 9876 }WSL2 里访问 Windows 版 Blender 时先试BLENDER_HOST127.0.0.1不通再换 Windows 主机 IP。截图是以 base64 随消息返回的不依赖共享临时目录所以这种跨环境场景照样能看视口。升级方式服务端uv cache clean blender-mcp uvx --refresh blender-mcp——先清缓存再刷新能治不少明明升过怎么还是旧版的怪病。插件端拿最新的addon.py替换旧文件同时在客户端配置里把 blender 服务删掉重新加一次。进阶玩法场景素材的三条来源这一节按素材从哪来分三路讲材质和光照的精细控制也归在第一路里。路线一本地直建——对话指令 任意 Python最简单的一路直接用自然语言描述场景AI 调工具一件件搭。要更细的控制时走execute_blender_code——它能在 Blender 里执行任意 Python这是材质光照控制最细的路径。比如你说把选中的物体改成磨砂玻璃质感背后执行的大概就是这类逻辑import bpy mat bpy.data.materials.new(FrostedGlass) mat.use_nodes True # 调 Principled BSDF 的透射/粗糙度后赋给物体⚠️ 任意代码执行等于把 Blender 的控制权整个交出去操作前先保存文件这是铁律。路线二外部素材库——Poly Haven 与 Sketchfab两条素材管道启用方式都是先在侧边栏 BlenderMCP 面板里勾选对应功能再用对话指挥库擅长什么怎么启用对 AI 说什么Poly HavenHDRI、贴图、现成模型侧边栏勾选即可用 Poly Haven 的 HDRI 做个雨天森林氛围地上摆几块岩石和灌木——AI 自动搜索、下载并把 HDRI 设为世界环境Sketchfab搜索导入具体物件填入 API KeyBLENDERMCP_SKETCHFAB_API_KEY去 Sketchfab 搜一张中世纪木椅并导入支持先看缩略图、确认后再下载还能按目标尺寸归一化椅子 1 米、桌子 0.75 米选素材的顺序可以记一句具体现成的物件先搜 Sketchfab通用环境、道具、氛围光交给 Poly Haven环境光直接用它的 HDRI。路线三AI 生成式建模——Hyper3D Rodin 与 Hunyuan3D库里都不满意时让 AI 现做。描述需求它生成自带材质的模型再导进场景Hyper3D Rodin比如用 Hyper3D 生成一条机械风格的蛇摆在场景角落。免费额度每天有次数上限重度使用建议申请自己的 KeyBLENDERMCP_HYPER3D_API_KEY。Hunyuan3D腾讯的 3D 生成在插件偏好里配置BLENDERMCP_HUNYUAN3D_SECRET_ID/BLENDERMCP_HUNYUAN3D_SECRET_KEY可选BLENDERMCP_HUNYUAN3D_API_URL。Key 都建议存在编辑 偏好设置 插件 Blender MCP里重启不丢。想看通信实现两个源码入口src/blender_mcp/server.py 里的BlenderConnection展示锁 socket 流怎么保证指令不乱序。addon.py插件端注册面板、端口与服务器的全部逻辑都在这里。BlenderMCP 连接不上怎么办按卡点分组的速查表这一节是排障用的先判断自己卡在流程哪一步再对号取解法。卡在哪一步典型现象可能原因解法客户端起不来报spawn uvx ENOENTGUI 客户端不继承终端 PATH找不到uvxwhich uvxmacOS/Linux或where uvxWindows取全路径填进commandWindows 也可走cmd /c写法。改完配置彻底退出客户端再重开服务端起了但连不上 Blender连接超时AI 说够不着 Blender插件端 socket 没在听或两边主机 / 端口对不上① 侧边栏确认显示运行中 ② 核对BLENDER_PORT与插件面板端口一致 ③ 防火墙放行 9876 ④ 确认是带界面的 Blender——blender -b后台模式下命令永远执行不了连上了但第一句没反应发指令后无反馈首次 socket 握手偶发丢包原样重发一遍即可响应慢或错乱命令长时间卡住后超时、流式响应串线单次请求太复杂socket 默认 180 秒超时或多个客户端同时在跑抢资源把大任务拆成小指令一步步喂同一时间只保留一个 MCP 客户端Cursor 和 Claude 别同时挂着Python 版本冲突uvx各种编译报错conda / pyenv 的 Python 与依赖不兼容Apple Silicon 上可能被拉去编 x86_64 包配置加args: [--python, 3.11, blender-mcp]与env: { UV_PYTHON_PREFERENCE: only-managed }Apple Silicon 换--python, 3.11-aarch64以上都试过还是不通反复重启无效客户端 / 服务端残留状态三连重置重启 Blender 插件 → 重启 MCP 客户端 → 把配置里的 blender 服务删掉重加基本覆盖九成疑难杂症行动清单与求助方式按顺序勾完这套 BlenderMCP 就算完整落地了☐ 装好 uv 并重启终端uvx --version有输出☐ 写好客户端 MCP 配置或 CLI 一行注册完全重启客户端☐ 装好addon.py侧边栏点 Connect确认状态为运行中☐ 发第一条建场景指令并追加一句截图确认让 AI 自查☐ 试一个外部素材库Poly Haven 或 Sketchfab☐ 把上面的故障速查表存下来留着下次救急如果哪一步卡住求助时请带上三样东西报错原文完整贴出别截图打码关键行、你用的客户端类型Claude 桌面版 / Cursor / CLI 之一和操作系统版本。有这三个信息问题基本能直接定位到上表某一行。【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
BlenderMCP 配置指南：从接入到排错的完整实战
BlenderMCP 配置指南从接入到排错的完整实战【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcpBlenderMCP 跑通之后你在 AI 客户端里敲一句话它就能在 Blender 里建物体、调材质、截视口图甚至执行任意 Python 代码——你说它动手。这篇文章只解决一件事把这套 BlenderMCP 配置从空白做到跑通并给你一张出问题能直接查的故障速查表。系统分两半跑在电脑上的 MCP 服务端进程负责跟大模型对话和住在 Blender 里的插件负责真正动手建模两边靠一条 TCP 套接字默认端口 9876交换指令与结果。适合不想手动点几百次菜单的建模师、想用 AI 加速原型的工作流控以及所有被连接超时spawn uvx ENOENT卡住过的人。接入前准备依赖清单与客户端选型这一节把硬件条件和入口先定下来避免装到一半发现环境不满足返工。最低依赖清单组件要求备注Blender3.0推荐 4.x / 5.x必须是带界面的正常会话blender -b后台模式跑不了命令Python3.10服务端由 uv 托管一般不用你操心uv最新版服务端的启动器兼包管理器装完要用uvx命令# macOS brew install uv # Linux curl -LsSf https://astral.sh/uv/install.sh | shWindows 在 PowerShell 里执行powershell -c irm https://astral.sh/uv/install.ps1 | iex⚠️ 两个容易翻车的点一是别用pip install uv凑合它经常不生成uvx命令二是 Windows 装完要把%USERPROFILE%\.local\bin加进 PATH 并重启终端。最后用uvx --version验证一下有输出才算装好。三种客户端选型对比选哪条路接入决定了后面配置写法和会不会踩 Windows 的坑客户端需要什么条件特点Claude 桌面版claude_desktop_config.json里一段 JSON最标准的入口macOS / Linux 开箱即用Cursor同样的 MCP JSON 配置Windows 上需要借cmd绕一道见下文Claude Code CLI不用配置文件终端里一行命令完成注册适合纯命令行工作流BlenderMCP 安装与第一条指令四步接通这一节按配客户端 → 装插件 → 连接 → 说话的顺序一次讲完跑完你手里就是一个能对话的 Blender。第 1 步客户端指向 blender-mcp。以 Claude 桌面版为例进设置 开发者 编辑配置往claude_desktop_config.json里贴{ mcpServers: { blender: { command: uvx, args: [blender-mcp] } } }含义就一句让 Claude 启动时通过uvx拉起名为blender-mcp的服务。贴完把客户端完全退出再重开它才会重新读配置。第 2 步把插件装进 Blender。从仓库根目录拿addon.py整个插件就这一个文件编辑 偏好设置 插件 安装…选中它然后在列表里勾选启用Interface: Blender MCP。第 3 步点 Connect。在 3D 视图按N唤出侧边栏切到BlenderMCP标签点Connect to Claude。侧边栏状态显示运行中说明插件端就绪回到 Claude工具列表里出现锤子图标代表 Blender 工具已挂上。第 4 步说出第一句话。发一句具体的指令比如建一个等轴视角的小房间灰色地板、三根白色方柱后墙中间放一扇木门。 第一条指令偶尔没反应别慌——首次 socket 握手容易丢一次包原样再发一遍通常就通了。接着一句别停追加截个视口图确认一下刚才建出来的东西。这一步会让 AI 真的看到场景它基于截图自查哪不对你直接说把木门往左挪半个柱距它再去修。这样操作 → 截图验证 → 修正的闭环就形成了比让它盲改可靠得多。BlenderMCP 配置详解总表与三类部署环境这一节把所有可动参数集中起来。如果你只是标准单机接入看懂总表前几行就够其余环境按需取用。总配置表配置项所在位置默认值什么时候改BLENDER_HOST服务端环境变量localhostBlender 跑在容器 / 远程机器时改成 MCP 进程够得着的地址BLENDER_PORT服务端环境变量9876端口被占用时换号比如9877插件端 Port 属性Blender 侧边栏输入框9876跟BLENDER_PORT走两边必须一致BLENDER_MCP_DISABLE_TELEMETRY环境变量未设置匿名统计开启设成true彻底关闭也可在插件偏好里取消遥测勾选UV_PYTHON_PREFERENCE环境变量未设置机器上有 conda / pyenv 时设only-managed让 uv 用自管 Python端口一致性是最常见的隐形 bug服务端和插件各记一份端口一个 9876 一个 9877连接就永远握不上手。改完任何一边把另一边的值核对一遍。标准接入Claude 桌面版 / 命令行 CLI上面第 1 步的 JSON 就是标准答案。如果机器上 conda 或 pyenv 的 Python 版本打架给服务端钉一个干净的 3.11args: [--python, 3.11, blender-mcp], env: { UV_PYTHON_PREFERENCE: only-managed }Claude Code CLI 也算一种客户端只是不用配置文件终端里一行注册完事claude mcp add blender uvx blender-mcp等价的手动方式是自己在终端写好环境变量再拉起进程export BLENDER_HOSTlocalhost export BLENDER_PORT9876 export BLENDER_MCP_DISABLE_TELEMETRYtrue uvx blender-mcp⚠️ 别把uvx blender-mcp手动挂成长驻进程。它应该由 MCP 客户端在后台拉起你在终端手跑会看到它卡住半天没输出——那不是死机是它在安静等客户端连进来按Ctrl-C退出即可。完全不想用 uv 的话pipx install blender-mcp效果等价。Windows 与图形界面客户端Windows 的 GUI 程序不继承终端 PATHuvx经常被找不到让cmd先出场再执行command: cmd, args: [/c, uvx, blender-mcp]另一条路是写绝对路径where uvx查出来的完整路径直接填进command。macOS 和 Linux 的 Cursor 用户不需要这步直接用uvx那版。Apple Silicon 上如果uvx试图编 x86_64 的包常见于 cryptography 编译报错强制 arm64 解释器args: [--python, 3.11-aarch64, blender-mcp]。容器 / WSL / 远程主机原则一句话Blender 必须监听在 MCP 进程够得着的地方。在客户端配置里加一段envenv: { BLENDER_HOST: host.docker.internal, BLENDER_PORT: 9876 }WSL2 里访问 Windows 版 Blender 时先试BLENDER_HOST127.0.0.1不通再换 Windows 主机 IP。截图是以 base64 随消息返回的不依赖共享临时目录所以这种跨环境场景照样能看视口。升级方式服务端uv cache clean blender-mcp uvx --refresh blender-mcp——先清缓存再刷新能治不少明明升过怎么还是旧版的怪病。插件端拿最新的addon.py替换旧文件同时在客户端配置里把 blender 服务删掉重新加一次。进阶玩法场景素材的三条来源这一节按素材从哪来分三路讲材质和光照的精细控制也归在第一路里。路线一本地直建——对话指令 任意 Python最简单的一路直接用自然语言描述场景AI 调工具一件件搭。要更细的控制时走execute_blender_code——它能在 Blender 里执行任意 Python这是材质光照控制最细的路径。比如你说把选中的物体改成磨砂玻璃质感背后执行的大概就是这类逻辑import bpy mat bpy.data.materials.new(FrostedGlass) mat.use_nodes True # 调 Principled BSDF 的透射/粗糙度后赋给物体⚠️ 任意代码执行等于把 Blender 的控制权整个交出去操作前先保存文件这是铁律。路线二外部素材库——Poly Haven 与 Sketchfab两条素材管道启用方式都是先在侧边栏 BlenderMCP 面板里勾选对应功能再用对话指挥库擅长什么怎么启用对 AI 说什么Poly HavenHDRI、贴图、现成模型侧边栏勾选即可用 Poly Haven 的 HDRI 做个雨天森林氛围地上摆几块岩石和灌木——AI 自动搜索、下载并把 HDRI 设为世界环境Sketchfab搜索导入具体物件填入 API KeyBLENDERMCP_SKETCHFAB_API_KEY去 Sketchfab 搜一张中世纪木椅并导入支持先看缩略图、确认后再下载还能按目标尺寸归一化椅子 1 米、桌子 0.75 米选素材的顺序可以记一句具体现成的物件先搜 Sketchfab通用环境、道具、氛围光交给 Poly Haven环境光直接用它的 HDRI。路线三AI 生成式建模——Hyper3D Rodin 与 Hunyuan3D库里都不满意时让 AI 现做。描述需求它生成自带材质的模型再导进场景Hyper3D Rodin比如用 Hyper3D 生成一条机械风格的蛇摆在场景角落。免费额度每天有次数上限重度使用建议申请自己的 KeyBLENDERMCP_HYPER3D_API_KEY。Hunyuan3D腾讯的 3D 生成在插件偏好里配置BLENDERMCP_HUNYUAN3D_SECRET_ID/BLENDERMCP_HUNYUAN3D_SECRET_KEY可选BLENDERMCP_HUNYUAN3D_API_URL。Key 都建议存在编辑 偏好设置 插件 Blender MCP里重启不丢。想看通信实现两个源码入口src/blender_mcp/server.py 里的BlenderConnection展示锁 socket 流怎么保证指令不乱序。addon.py插件端注册面板、端口与服务器的全部逻辑都在这里。BlenderMCP 连接不上怎么办按卡点分组的速查表这一节是排障用的先判断自己卡在流程哪一步再对号取解法。卡在哪一步典型现象可能原因解法客户端起不来报spawn uvx ENOENTGUI 客户端不继承终端 PATH找不到uvxwhich uvxmacOS/Linux或where uvxWindows取全路径填进commandWindows 也可走cmd /c写法。改完配置彻底退出客户端再重开服务端起了但连不上 Blender连接超时AI 说够不着 Blender插件端 socket 没在听或两边主机 / 端口对不上① 侧边栏确认显示运行中 ② 核对BLENDER_PORT与插件面板端口一致 ③ 防火墙放行 9876 ④ 确认是带界面的 Blender——blender -b后台模式下命令永远执行不了连上了但第一句没反应发指令后无反馈首次 socket 握手偶发丢包原样重发一遍即可响应慢或错乱命令长时间卡住后超时、流式响应串线单次请求太复杂socket 默认 180 秒超时或多个客户端同时在跑抢资源把大任务拆成小指令一步步喂同一时间只保留一个 MCP 客户端Cursor 和 Claude 别同时挂着Python 版本冲突uvx各种编译报错conda / pyenv 的 Python 与依赖不兼容Apple Silicon 上可能被拉去编 x86_64 包配置加args: [--python, 3.11, blender-mcp]与env: { UV_PYTHON_PREFERENCE: only-managed }Apple Silicon 换--python, 3.11-aarch64以上都试过还是不通反复重启无效客户端 / 服务端残留状态三连重置重启 Blender 插件 → 重启 MCP 客户端 → 把配置里的 blender 服务删掉重加基本覆盖九成疑难杂症行动清单与求助方式按顺序勾完这套 BlenderMCP 就算完整落地了☐ 装好 uv 并重启终端uvx --version有输出☐ 写好客户端 MCP 配置或 CLI 一行注册完全重启客户端☐ 装好addon.py侧边栏点 Connect确认状态为运行中☐ 发第一条建场景指令并追加一句截图确认让 AI 自查☐ 试一个外部素材库Poly Haven 或 Sketchfab☐ 把上面的故障速查表存下来留着下次救急如果哪一步卡住求助时请带上三样东西报错原文完整贴出别截图打码关键行、你用的客户端类型Claude 桌面版 / Cursor / CLI 之一和操作系统版本。有这三个信息问题基本能直接定位到上表某一行。【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考