Metadata-Version: 2.4
Name: blender-mcp-hortor
Version: 1.5.6
Summary: Blender integration through the Model Context Protocol
Author: silwings1986
License: MIT
Project-URL: Homepage, https://github.com/silwings1986/blender-mcp
Project-URL: Bug Tracker, https://github.com/silwings1986/blender-mcp/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.3.0
Requires-Dist: supabase>=2.0.0
Requires-Dist: tomli>=2.0.0
Dynamic: license-file

# BlenderMCP-Hortor

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

> 本项目基于 [ahujasid/blender-mcp](https://github.com/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 包管理器](https://docs.astral.sh/uv/getting-started/installation/)

**Mac 安装 uv：**

```bash
brew install uv
```

**Windows 安装 uv：**

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

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

```powershell
$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：**

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

**Windows：**

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

### Claude Desktop 配置

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

**Mac / Linux：**

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

**Windows：**

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

### Visual Studio Code 配置

在 VS Code 的 MCP 设置中添加：

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

### 环境变量

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

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

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

```json
{
    "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. **环境变量**：完全禁用遥测：

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

## 安全提示

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

## 许可证

MIT License
