BlenderMCP安装与配置指南从跑通到排障【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcp当你在 Blender 里想用一句话直接造出 3D 场景时BlenderMCP 就能让 AI 助手实时创建、修改 Blender 中的对象。本文带你完成 uv 安装、客户端配置和插件接入三个环节覆盖最短路径跑通、环境变量逐项说明、端口占用与多客户端冲突的排查顺序。先跑通最短路径接入按顺序执行 6 步先看到连上了的信号再回头补细节。安装 uvAstral 出品的 Python 包管理器uvx是它的一次性运行命令# macOS brew install uv # Linux curl -LsSf https://astral.sh/uv/install.sh | sh # WindowsPowerShell powershell -c irm https://astral.sh/uv/install.ps1 | iex安装后在终端确认uvx --version有输出。Windows 用户需把%USERPROFILE%\.local\bin加入 PATH然后重启客户端。获取插件文件。如果仓库已克隆git clone https://gitcode.com/GitHub_Trending/bl/blender-mcp直接使用根目录的 addon.py否则从项目仓库下载该文件。Blender 中依次点击 编辑 偏好设置 插件 安装...选择addon.py。启用Interface: Blender MCP插件关闭偏好设置窗口。在 Claude Desktop 中打开 设置 开发者 编辑配置把以下内容写入claude_desktop_config.json再完全退出并重启 Claude Desktop{ mcpServers: { blender: { command: uvx, args: [blender-mcp] } } }回到 Blender在 3D 视图按N打开侧边栏切到BlenderMCP选项卡点击Connect to Claude。成功信号侧边栏状态变为已连接同时 Claude 对话界面出现锤子图标表示 Blender 工具已激活。此时发一句Create a low poly dungeon with a dragon guarding gold场景里会开始出物体。⚠️ 不要手动在终端运行uvx blender-mcp——MCP 服务器由客户端自动拉起手动多开会导致连接状态混乱。 不要用pip install uv安装 uv它可能不生成uvx命令。它是怎么工作的三个组件一条 TCP 线整条链路只有三个组件各管一段AI 客户端Claude Desktop / Cursor / VS Code你输入提示词的地方它负责按配置自动启动uvx blender-mcp。MCP 服务器src/blender_mcp/server.py实现模型上下文协议MCP一种让 LLM 调用外部工具的开放协议把 AI 的工具调用翻译成套接字命令并读取BLENDER_HOST/BLENDER_PORT决定连向哪里。Blender 插件addon.py在 Blender 进程内开一个 TCP 套接字服务器默认 9876 端口收到命令后执行建对象、改材质、跑 Python再把结果以 JSON 返回。调用方向是单向链客户端 --MCP/stdio-- 服务器 --TCP:9876-- 插件。一次调用的报文长这样{ type: create_object, params: { type: SPHERE, name: Ball } } { status: success, result: { name: Ball, location: [0, 0, 0] } }插件侧的连接入口在侧边栏截图如下配置逐项说明环境变量与配置文件所有连接参数都通过环境变量注入MCP 服务器启动时读取。改的位置只有两处终端手动运行时或客户端配置里的env字段客户端托管时推荐。参数默认值作用BLENDER_HOSTlocalhost插件套接字服务器所在主机服务器会按候选顺序依次尝试连接BLENDER_PORT9876套接字端口Blender 侧必须与之一致BLENDER_MCP_DISABLE_TELEMETRY未设置设为true关闭匿名使用统计工具名、耗时等手动运行时这样注入export BLENDER_HOSTlocalhost export BLENDER_PORT9876 uvx blender-mcp客户端托管时在配置里加env字段env: { BLENDER_HOST: localhost, BLENDER_PORT: 9876 }Claude Desktop用「先跑通」一节的配置即可。如果你的机器上 conda / pyenv 的 Python 与 uv 冲突把args改成[--python, 3.11, blender-mcp]并加env: { UV_PYTHON_PREFERENCE: only-managed }让 uv 只用自己管理的解释器。CursormacOS / Linux 与 Claude Desktop 完全相同。Windows 上uvx不是原生可执行文件需要套一层cmd{ mcpServers: { blender: { command: cmd, args: [/c, uvx, blender-mcp] } } }VS Code 与其他客户端VS Code 的 MCP 配置结构与上面一致commandargs。Claude Code CLI 可以一条命令注册claude mcp add blender uvx blender-mcpDocker / WSL / 远程主机Blender 和 MCP 服务器不在同一台机器时把BLENDER_HOST指向 Blender 一侧可达的地址。Docker 里连宿主机 Blender 用host.docker.internal服务器还会自动尝试172.17.0.1WSL2 里连 Windows 的 Blender先试127.0.0.1不通再换成 Windows 宿主机的 IP。验证与排障连接不上时的排查顺序从最常见到最少见按顺序逐条核对每条先认现象、再给动作。第一条提示词失败、后续正常插件服务器刚启动时首条命令经常丢失。现象是首次调用报错但场景没变化动作是原样重发一次并确认侧边栏显示已连接。客户端报spawn uvx ENOENTGUI 客户端不继承终端 PATH找不到uvx。动作是终端执行which uvxmacOS/Linux或where uvxWindows把输出的完整路径填进配置的command改完完全重启客户端。端口 9876 被占用现象是插件点击 Connect 失败或 MCP 服务器报Could not connect to Blender (tried ...)。同一时间只能有一个进程监听 9876。动作是确认没有残留的旧 Blender 进程或手动起的uvx实例确需并存时把双方的BLENDER_PORT同步改成别的值。多客户端冲突同时开 Cursor 和 Claude Desktop 各跑一个 MCP 服务器时两个服务器抢同一条到插件的 TCP 连接表现为指令时灵时不灵、状态反复断开。动作是只保留一个客户端在跑另一个从配置里移除README 明确建议一次只跑一个。跨环境连不通现象是本地localhost明明没问题容器/WSL 里却超时。动作是核对「配置逐项说明」最后一节的BLENDER_HOST取值并用报错里tried ...列出的候选确认服务器实际尝试过哪些地址。复杂场景请求超时现象是让 AI 一次搭建完整场景时中途超时。动作是把请求拆成多轮小步骤先建结构、再加材质、最后布光。Python 版本冲突 / cryptography 报错常见于 Apple Silicon 上误用 x86_64 解释器。动作是在args里加--python参数如[--python, 3.11-aarch64, blender-mcp]再清缓存uv cache clean blender-mcp uvx --refresh blender-mcp。以上都不对症动作是重启 MCP 客户端、重启 Blender 插件服务器然后只发一条最简单的指令如新建一个球体复测。进阶用法可直接复用的示例验证链路是否完整场景刚装好想确认 AI 真能操控 BlenderCreate a low poly dungeon with a dragon guarding gold写实氛围搭建场景需要真实光照与材质先在侧边栏勾选 Poly Haven 复选框再发Beach scene with Poly Haven HDRIs, rocks, and vegetation局部改材质场景已有模型只想改外观不用重建Make this car red and metallic不想上报匿名统计时在配置的env里加BLENDER_MCP_DISABLE_TELEMETRY: true或手动运行时BLENDER_MCP_DISABLE_TELEMETRYtrue uvx blender-mcp注意execute_blender_code工具会在 Blender 内执行任意 Python用它改动场景前先保存工程。完整功能列表Poly Haven、Sketchfab、Hyper3D 等集成与 API 凭据存放位置见官方文档 README.md遇到问题可参考 SECURITY.md 了解遥测细节或在项目仓库的 Issues 区提问。【免费下载链接】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-mcp当你在 Blender 里想用一句话直接造出 3D 场景时BlenderMCP 就能让 AI 助手实时创建、修改 Blender 中的对象。本文带你完成 uv 安装、客户端配置和插件接入三个环节覆盖最短路径跑通、环境变量逐项说明、端口占用与多客户端冲突的排查顺序。先跑通最短路径接入按顺序执行 6 步先看到连上了的信号再回头补细节。安装 uvAstral 出品的 Python 包管理器uvx是它的一次性运行命令# macOS brew install uv # Linux curl -LsSf https://astral.sh/uv/install.sh | sh # WindowsPowerShell powershell -c irm https://astral.sh/uv/install.ps1 | iex安装后在终端确认uvx --version有输出。Windows 用户需把%USERPROFILE%\.local\bin加入 PATH然后重启客户端。获取插件文件。如果仓库已克隆git clone https://gitcode.com/GitHub_Trending/bl/blender-mcp直接使用根目录的 addon.py否则从项目仓库下载该文件。Blender 中依次点击 编辑 偏好设置 插件 安装...选择addon.py。启用Interface: Blender MCP插件关闭偏好设置窗口。在 Claude Desktop 中打开 设置 开发者 编辑配置把以下内容写入claude_desktop_config.json再完全退出并重启 Claude Desktop{ mcpServers: { blender: { command: uvx, args: [blender-mcp] } } }回到 Blender在 3D 视图按N打开侧边栏切到BlenderMCP选项卡点击Connect to Claude。成功信号侧边栏状态变为已连接同时 Claude 对话界面出现锤子图标表示 Blender 工具已激活。此时发一句Create a low poly dungeon with a dragon guarding gold场景里会开始出物体。⚠️ 不要手动在终端运行uvx blender-mcp——MCP 服务器由客户端自动拉起手动多开会导致连接状态混乱。 不要用pip install uv安装 uv它可能不生成uvx命令。它是怎么工作的三个组件一条 TCP 线整条链路只有三个组件各管一段AI 客户端Claude Desktop / Cursor / VS Code你输入提示词的地方它负责按配置自动启动uvx blender-mcp。MCP 服务器src/blender_mcp/server.py实现模型上下文协议MCP一种让 LLM 调用外部工具的开放协议把 AI 的工具调用翻译成套接字命令并读取BLENDER_HOST/BLENDER_PORT决定连向哪里。Blender 插件addon.py在 Blender 进程内开一个 TCP 套接字服务器默认 9876 端口收到命令后执行建对象、改材质、跑 Python再把结果以 JSON 返回。调用方向是单向链客户端 --MCP/stdio-- 服务器 --TCP:9876-- 插件。一次调用的报文长这样{ type: create_object, params: { type: SPHERE, name: Ball } } { status: success, result: { name: Ball, location: [0, 0, 0] } }插件侧的连接入口在侧边栏截图如下配置逐项说明环境变量与配置文件所有连接参数都通过环境变量注入MCP 服务器启动时读取。改的位置只有两处终端手动运行时或客户端配置里的env字段客户端托管时推荐。参数默认值作用BLENDER_HOSTlocalhost插件套接字服务器所在主机服务器会按候选顺序依次尝试连接BLENDER_PORT9876套接字端口Blender 侧必须与之一致BLENDER_MCP_DISABLE_TELEMETRY未设置设为true关闭匿名使用统计工具名、耗时等手动运行时这样注入export BLENDER_HOSTlocalhost export BLENDER_PORT9876 uvx blender-mcp客户端托管时在配置里加env字段env: { BLENDER_HOST: localhost, BLENDER_PORT: 9876 }Claude Desktop用「先跑通」一节的配置即可。如果你的机器上 conda / pyenv 的 Python 与 uv 冲突把args改成[--python, 3.11, blender-mcp]并加env: { UV_PYTHON_PREFERENCE: only-managed }让 uv 只用自己管理的解释器。CursormacOS / Linux 与 Claude Desktop 完全相同。Windows 上uvx不是原生可执行文件需要套一层cmd{ mcpServers: { blender: { command: cmd, args: [/c, uvx, blender-mcp] } } }VS Code 与其他客户端VS Code 的 MCP 配置结构与上面一致commandargs。Claude Code CLI 可以一条命令注册claude mcp add blender uvx blender-mcpDocker / WSL / 远程主机Blender 和 MCP 服务器不在同一台机器时把BLENDER_HOST指向 Blender 一侧可达的地址。Docker 里连宿主机 Blender 用host.docker.internal服务器还会自动尝试172.17.0.1WSL2 里连 Windows 的 Blender先试127.0.0.1不通再换成 Windows 宿主机的 IP。验证与排障连接不上时的排查顺序从最常见到最少见按顺序逐条核对每条先认现象、再给动作。第一条提示词失败、后续正常插件服务器刚启动时首条命令经常丢失。现象是首次调用报错但场景没变化动作是原样重发一次并确认侧边栏显示已连接。客户端报spawn uvx ENOENTGUI 客户端不继承终端 PATH找不到uvx。动作是终端执行which uvxmacOS/Linux或where uvxWindows把输出的完整路径填进配置的command改完完全重启客户端。端口 9876 被占用现象是插件点击 Connect 失败或 MCP 服务器报Could not connect to Blender (tried ...)。同一时间只能有一个进程监听 9876。动作是确认没有残留的旧 Blender 进程或手动起的uvx实例确需并存时把双方的BLENDER_PORT同步改成别的值。多客户端冲突同时开 Cursor 和 Claude Desktop 各跑一个 MCP 服务器时两个服务器抢同一条到插件的 TCP 连接表现为指令时灵时不灵、状态反复断开。动作是只保留一个客户端在跑另一个从配置里移除README 明确建议一次只跑一个。跨环境连不通现象是本地localhost明明没问题容器/WSL 里却超时。动作是核对「配置逐项说明」最后一节的BLENDER_HOST取值并用报错里tried ...列出的候选确认服务器实际尝试过哪些地址。复杂场景请求超时现象是让 AI 一次搭建完整场景时中途超时。动作是把请求拆成多轮小步骤先建结构、再加材质、最后布光。Python 版本冲突 / cryptography 报错常见于 Apple Silicon 上误用 x86_64 解释器。动作是在args里加--python参数如[--python, 3.11-aarch64, blender-mcp]再清缓存uv cache clean blender-mcp uvx --refresh blender-mcp。以上都不对症动作是重启 MCP 客户端、重启 Blender 插件服务器然后只发一条最简单的指令如新建一个球体复测。进阶用法可直接复用的示例验证链路是否完整场景刚装好想确认 AI 真能操控 BlenderCreate a low poly dungeon with a dragon guarding gold写实氛围搭建场景需要真实光照与材质先在侧边栏勾选 Poly Haven 复选框再发Beach scene with Poly Haven HDRIs, rocks, and vegetation局部改材质场景已有模型只想改外观不用重建Make this car red and metallic不想上报匿名统计时在配置的env里加BLENDER_MCP_DISABLE_TELEMETRY: true或手动运行时BLENDER_MCP_DISABLE_TELEMETRYtrue uvx blender-mcp注意execute_blender_code工具会在 Blender 内执行任意 Python用它改动场景前先保存工程。完整功能列表Poly Haven、Sketchfab、Hyper3D 等集成与 API 凭据存放位置见官方文档 README.md遇到问题可参考 SECURITY.md 了解遥测细节或在项目仓库的 Issues 区提问。【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考