blender-mcp-hortor 1.5.6

Blender integration through the Model Context Protocol

BlenderMCP-Hortor

BlenderMCP-Hortor 通过 Model Context Protocol (MCP) 将 Blender 连接到 AI 助手（Claude、Cursor、VS Code 等），实现 AI 驱动的 3D 建模、场景创建与操作。

本项目基于 ahujasid/blender-mcp 开发。

功能特性

• 双向通信：通过 Socket 服务器连接 AI 与 Blender
• 对象操作：创建、修改、删除 3D 对象
• 材质控制：应用和修改材质与颜色
• 场景检查：获取当前 Blender 场景的详细信息
• 代码执行：在 Blender 中执行 Python 代码
• Poly Haven 资产：下载模型、纹理和 HDRI
• AI 3D 模型生成：支持 Hyper3D Rodin、Hunyuan3D、Meshy.ai
• Sketchfab 模型：搜索和下载 Sketchfab 模型
• 视口截图：截取 Blender 视口图片以便 AI 理解场景

系统组件

1. Blender 插件 (addon.py)：在 Blender 内部创建 Socket 服务器，接收和执行命令
2. MCP Server (src/blender_mcp/server.py)：实现 MCP 协议，连接 AI 助手与 Blender 插件

安装

前置条件

• Blender 3.0 或更新版本
• Python 3.10 或更新版本
• uv 包管理器

Mac 安装 uv：

brew install uv

Windows 安装 uv：

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

安装后将 uv 添加到用户 PATH（可能需要重启编辑器）：

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

安装 Blender 插件

1. 下载本仓库的 addon.py 文件
2. 打开 Blender → Edit → Preferences → Add-ons
3. 点击 "Install..."，选择下载的 addon.py
4. 勾选 "Interface: Blender MCP" 启用插件

Cursor 配置

进入 Settings → MCP → Add Server，粘贴以下配置：

• 全局使用：点击 "add new global MCP server"
• 项目级使用：在项目根目录创建 .cursor/mcp.json

Mac / Linux：

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

Windows：

{
    "mcpServers": {
        "blender": {
            "command": "cmd",
            "args": [
                "/c",
                "uvx",
                "blender-mcp-hortor"
            ]
        }
    }
}

Claude Desktop 配置

进入 Claude → Settings → Developer → Edit Config → claude_desktop_config.json：

Mac / Linux：

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

Windows：

{
    "mcpServers": {
        "blender": {
            "command": "cmd",
            "args": [
                "/c",
                "uvx",
                "blender-mcp-hortor"
            ]
        }
    }
}

Visual Studio Code 配置

在 VS Code 的 MCP 设置中添加：

{
    "servers": {
        "blender": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "blender-mcp-hortor"
            ]
        }
    }
}

环境变量

可通过环境变量配置 Blender 连接参数：

变量名	说明	默认值
BLENDER_HOST	Blender Socket 服务器地址	localhost
BLENDER_PORT	Blender Socket 服务器端口	9876

在 MCP 配置中使用环境变量的示例：

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["blender-mcp-hortor"],
            "env": {
                "BLENDER_HOST": "localhost",
                "BLENDER_PORT": "9876"
            }
        }
    }
}

使用方法

启动连接

1. 在 Blender 中，打开 3D 视口侧边栏（按 N 键）
2. 找到 "BlenderMCP" 标签页
3. 如需 Poly Haven 资产，勾选对应选项
4. 点击 "Connect to Claude"
5. 确保 MCP Server 已在编辑器中运行

⚠️ 同一时间只运行一个 MCP Server 实例（Cursor 或 Claude Desktop，不要同时运行）

使用示例

以下是一些可以让 AI 完成的操作示例：

• "创建一个低多边形的地牢场景，有一条龙守护着一罐金币"
• "用 Poly Haven 的 HDRI、纹理和模型创建一个海滩场景"
• "根据这张参考图创建 Blender 场景"
• "通过 Hyper3D 生成一个花园侏儒的 3D 模型"
• "把这辆车改成红色金属材质"
• "创建一个球体并放在方块上方"
• "设置成摄影棚灯光效果"
• "把摄像机对准场景，并设为等距视角"

故障排除

• 连接失败：确保 Blender 插件服务器正在运行，MCP Server 已在编辑器中配置，不要手动在终端运行 uvx 命令
• 超时错误：尝试简化请求或拆分为更小的步骤
• 连接仍有问题：重启编辑器和 Blender 插件

遥测控制

BlenderMCP 收集匿名使用数据用于改进工具。可通过以下方式控制：

1. Blender 内：Edit → Preferences → Add-ons → Blender MCP，取消勾选遥测选项
2. 环境变量：完全禁用遥测：

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["blender-mcp-hortor"],
            "env": {
                "DISABLE_TELEMETRY": "true"
            }
        }
    }
}

安全提示

• execute_blender_code 工具允许在 Blender 中运行任意 Python 代码，使用前请务必保存你的工作
• Poly Haven 需要下载模型、纹理和 HDRI 图片，如不需要请在 Blender 中关闭
• 复杂操作可能需要拆分为更小的步骤

许可证

MIT License