blender-mcp

环境要求

• 已安装并可正常打开的 Blender 3D
• 已安装 uv（必须用官方安装脚本，官方明确禁止 pip install uv）
• 一个支持 MCP 的 LLM 客户端（Claude、GPT 等）
• 可选：Docker（把 MCP 服务端跑在容器里，Blender 仍在本机运行）
• 可选：pipx（用于受限机器，跳过 uvx）

安装与启动步骤

1. 1安装 uv

   macOS 可用 brew install uv，Windows 用 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"。必须用官方安装脚本，不要用 pip install

   curl -LsSf https://astral.sh/uv/install.sh | sh

   复制

2. 2安装 Blender 插件

   在终端执行，插件会以 blender_mcp.py 写入 Blender 插件目录并打印路径，覆盖旧文件时会保留 .bak 备份。

   uvx blender-mcp install-addon

   复制

3. 3启用插件

   打开 Blender，进入 Edit → Preferences → Add-ons，搜索并勾选 Interface: MCP for Blender；若列表中没有，点 Install… 选择复制过去的 blender_mcp.py 或重启

4. 4启动 MCP 服务端

   在 3D 视口按 N 打开侧边栏，切到 MCP for Blender 标签页，点击 Start MCP Server 让插件开始监听。

5. 5构建 Docker 镜像

   仅 Docker 方式需要：先克隆仓库，在仓库根目录构建镜像；Blender 本身仍运行在宿主机上，容器只跑 MCP 服务端。

   git clone https://github.com/ahujasid/blender-mcp.git
   cd blender-mcp
   docker build -t blender-mcp .

   复制

6. 6配置 MCP 客户端

   把下面的配置写入客户端 MCP 配置。Docker 运行时 -i 参数必须保留，因为服务端通过 stdin/stdout 与客户端通信。

   {
       "mcpServers": {
           "blender": {
               "command": "docker",
               "args": ["run", "-i", "--rm", "blender-mcp"]
           }
       }
   }

   复制

关键配置

如何确认成功

Blender 侧边栏点击 Start MCP Server 后服务端启动，MCP 客户端能连上并调用 Blender 工具。

常见问题

注意事项

• 这是第三方集成，并非 Blender 官方项目。
• Docker 方式只把 MCP 服务端放进容器，Blender 必须仍然运行在宿主机上。
• 使用 uvx blender-mcp addon-paths 可以列出检测到的 Blender 插件目录；替换目标目录用 BLENDERMCP_ADDONS_DIR。
• 插件安装命令覆盖已有文件时会保留 .bak 备份。