Blender MCP

这是一个让 Claude AI 通过 MCP (Model Context Protocol) 直接控制 Blender 3D 的工具。

通过自然语言下达指令，Claude 会自动在 Blender 场景中执行对象创建、修改、删除和 Python 代码运行。

工作原理

Claude Desktop
     │ MCP (stdio / HTTP·SSE)
     ▼
MCP Server (Python)          ← 이 저장소
     │ TCP Socket :9999
     ▼
Blender Add-on (Python)      ← 이 저장소
     │ bpy API
     ▼
Blender 씬

Related MCP server: BlenderMCP

要求

安装方法

第 1 步 — 克隆仓库

git clone https://github.com/nowcika/blender_mcp.git
cd blender_mcp

第 2 步 — 安装 MCP 服务器依赖

pip install -r requirements.txt

requirements.txt 内容: mcp>=1.0.0

第 3 步 — 安装 Blender 插件

首先将 addon/ 文件夹压缩为 zip 文件：

# 터미널에서 프로젝트 루트 위치에서 실행
cd addon
zip -r ../blender_mcp_addon.zip .
cd ..

现在安装到 Blender 中：

1. 点击 Blender 屏幕顶部菜单栏的 编辑 (Edit)

2. 点击 偏好设置 (Preferences)

3. 点击偏好设置窗口左侧的 插件 (Add-ons)

4. 点击右上角的 下拉箭头 (⌄) → 从磁盘安装 (Install from Disk)

5. 选择刚才创建的 blender_mcp_addon.zip 文件

6. 点击 安装插件 (Install Add-on) 按钮

7. 勾选列表中出现的 "Blender MCP" 项目左侧的复选框以启用

第 4 步 — 在 Blender 中启动 Socket 服务器

什么是 3D 视图？ 打开 Blender 后，中间可以看到一个巨大的 3D 空间。这是放置和操作对象的主要工作区域。 什么是侧边栏？ 在 3D 视图中按下键盘 N 键，右侧会打开一个面板。这就是侧边栏。

1. 将鼠标光标悬停在 Blender 中间的 3D 视图 区域上

2. 按下键盘 N 键 → 右侧打开侧边栏面板

3. 点击侧边栏顶部的 MCP 选项卡

4. 点击 Start MCP Server 按钮

5. 当按钮上方的状态显示为 Running 时，即准备就绪

如果 N 键没反应：请确保鼠标光标位于 3D 视图内。Blender 的快捷键取决于鼠标位置。

默认端口：9999。如需更改，请设置环境变量：

BLENDER_MCP_PORT=9998  # Blender 실행 전 설정

Claude Desktop 集成 (stdio — 推荐)

在 claude_desktop_config.json 文件中添加以下内容。

文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "blender": {
      "command": "python3",
      "args": ["-m", "server", "--transport", "stdio"],
      "cwd": "/절대경로/blender_mcp"
    }
  }
}

请将 /绝对路径/blender_mcp 替换为实际的克隆路径。 Windows 示例: "cwd": "C:\\Users\\yourname\\blender_mcp"

设置完成后，重启 Claude Desktop。

Claude Code (终端 CLI) 集成

如果您在终端中使用 claude 命令而不是 Claude Desktop。

方法 1 — 在项目文件夹中自动识别 (推荐)

本仓库包含 .mcp.json 文件。 在 blender_mcp 文件夹内运行 claude 时，MCP 服务器会自动注册。

cd blender_mcp
claude        # .mcp.json을 자동으로 읽어서 blender MCP 활성화

方法 2 — 全局注册以便随时使用

将 /绝对路径/blender_mcp 替换为实际路径并输入到终端：

claude mcp add --scope user blender python3 /절대경로/blender_mcp/start_server.py

示例 (Windows)：

claude mcp add --scope user blender python3 C:/Users/yourname/blender_mcp/start_server.py

确认注册：

claude mcp list

HTTP/SSE 模式 (远程连接)

用于从远程服务器控制非本地的 Blender。

# MCP 서버를 HTTP 모드로 실행
python3 -m server --transport http --host 0.0.0.0 --port 8080

Claude Desktop 设置：

{
  "mcpServers": {
    "blender": {
      "url": "http://서버IP:8080/sse"
    }
  }
}

可用的 MCP 工具

与 Claude 对话时，以下工具会自动激活。

使用示例

在 Claude Desktop 聊天窗口中：

큐브 하나 만들어줘
→ Claude가 create_object 도구 호출 → Blender에 Cube 생성

방금 만든 큐브를 (3, 0, 1)로 이동하고 45도 회전해줘
→ Claude가 modify_object 호출 → 위치·회전 적용

현재 씬에 있는 모든 오브젝트 목록 알려줘
→ Claude가 get_scene_info 호출 → 오브젝트 목록 반환

环境变量设置

故障排除

"Blender is not running" 错误

• 确认 Blender 是否正在运行

• 确认是否在 3D 视图中按 N 键 → MCP 选项卡 → 点击了 Start MCP Server 按钮

• 确认防火墙没有拦截 9999 端口

插件未出现在列表中

• 确认 Blender 版本是否为 4.2 或以上 (在屏幕顶部 帮助 (Help) → 关于 Blender (About Blender) 中查看)

• addon/ 文件夹内的文件必须直接位于 zip 根目录下。请按以下方式重新压缩：

# 올바른 압축 방법 (addon/ 폴더 안에서 실행)
cd addon
zip -r ../blender_mcp_addon.zip .
cd ..

MCP 服务器无法连接

# 의존성 확인
pip show mcp

# 서버 직접 테스트 (stdio 대신 로그 확인용)
python3 -m server --transport http --port 8080
# http://localhost:8080/sse 접근해서 응답 확인

项目结构

blender_mcp/
├── addon/
│   ├── __init__.py           # Blender Add-on + 소켓 서버
│   ├── executor.py           # bpy 명령 실행기
│   └── blender_manifest.toml # Blender 5.x Extension 매니페스트
├── server/
│   ├── __init__.py           # MCP 서버 진입점 (stdio / HTTP)
│   ├── tools.py              # MCP 도구 6개 정의
│   └── blender_client.py     # Blender 소켓 클라이언트
├── requirements.txt
└── README.md

许可证

GPL-3.0-or-later