使用说明

Blender MCP服务器v2

为Antigravity、VSCode/Cox和其他MCP客户端提供AI驱动的3D创建。

一个生产就绪的MCP（模型上下文协议）服务器，允许AI客户端直接通过自然语言控制Blender。创建3D模型、应用材质、雕刻网格、渲染预览、导出资源和运行自定义 bpy 文本提示中的代码。

这个项目最初是为Antigravity IDE编写的，但服务器使用标准的MCP over stdio。只要客户端支持stdio MCP服务器，它也可以从VSCode MCP集成中使用，包括ChatGPT/Codex扩展。

特性

标准MCP服务器 -运行在stdio上，可以由Antigravity、VSCode/Code或任何兼容的MCP客户端启动。
17搅拌机工具 -从原始创作到人工智能辅助雕刻。
蓝图系统 -建筑物、武器、车辆和机器人的结构模型生成。
材质和纹理工具 -应用材质预设、图像纹理和生成的纹理。
视觉反馈 -渲染或预览场景，以便AI可以检查结果并进行修改。
令牌优化响应 -紧凑的JSON响应，实现高效的工具调用。
跨平台桥梁 -TypeScript MCP服务器通过WebSocket与Blender Python插件通信。
标准稳定性修复 -服务器入口点使MCP进程对VSCode/Copyx等stdio客户端保持活动状态。

可用工具

#	工具	说明
1	`status`	检查搅拌机连接
2	`scene`	列出场景中的对象
3	`prim`	创建基本体（立方体、球体、圆柱体等）
4	`export`	出口型号（GLB、FBX、OBJ）
5	`tex`	从文件中应用纹理
6	`mat`	设置材料（金属、玻璃、木材、光泽等）
7	`proc`	程序生成（树木、岩石、地形）
8	`opt`	优化/抽取网格
9	`render`	全质量渲染
10	`bake`	烘焙纹理（法线、AO、漫反射）
11	`gentex`	AI纹理生成+应用
12	`pipe`	分步工作流编排器
13	`parse`	从结构上分析提示
14	`blueprint`	从结构生成复杂模型
15	`sculpt`	人工智能辅助网格修改
16	`preview`	AI视觉反馈的快速渲染
17	`run`	执行自定义Python/bpy代码

需求

搅拌机 4.0+;使用Blender 5.1.1进行本地验证。
Node.js 20+;该包声明 >=20.0.0.
npm 用于安装依赖关系。
MCP客户端，例如反重力IDE、支持MCP的VSCode或VSCode ChatGPT/Codex。
可选： WSL 2 当MCP服务器在Linux中运行，Blender在Windows上运行时。

注意：原始项目是针对《反重力》中的Gemini 3 Pro进行优化的。这是对复杂3D推理的模型建议，而不是硬性协议要求。服务器本身是标准的MCP，并已通过VSCode/Cox验证。

安装

1.克隆存储库

git clone https://github.com/YOUR_USERNAME/blender-mcp-v2.git
cd blender-mcp-v2

2.安装节点依赖关系

cd src/mcp-server
npm ci
npm run build

使用 npm install 如果您正在开发并有意更新 package-lock.json.

3.安装Blender插件

打开 搅拌机4.0+
首选 Edit → 偏好→ 附加组件
点击 安装。..
导航至 blender-mcp-v2/src/blender-addon/mcp_connector_v2.py
选择文件并单击 安装附加组件
启用复选框 “接口：MCP连接器v2”
点击 保存首选项

4.启动Blender服务器

在Blender中，按 N 打开侧边栏
找到 主控程序 标签
点击 启动服务器
状态应显示： Running on ws://0.0.0.0:9876 或 Running on ws://127.0.0.1:9876
Windows防火墙： 如果被问到，允许Python/Blender仅在私人网络（如果使用WSL，则为公共网络）。

MCP客户端配置

TypeScript MCP服务器以以下代码开头：

node /FULL/PATH/TO/blender-mcp-v2/src/mcp-server/dist/index.js

然后，MCP服务器连接到Blender插件：

ws://127.0.0.1:9876

使用 BLENDER_HOST 和 BLENDER_PORT 当Blender在默认端点无法访问时。

VSCode/Codex

VSCode MCP配置使用 servers 对象。在Linux上，用户级配置通常是：

~/.config/Code/User/mcp.json

Linux配置示例：

{
  "inputs": [],
  "servers": {
    "blender-mcp": {
      "type": "stdio",
      "command": "/FULL/PATH/TO/node",
      "args": [
        "/FULL/PATH/TO/blender-mcp-v2/src/mcp-server/dist/index.js"
      ],
      "env": {
        "BLENDER_HOST": "127.0.0.1",
        "BLENDER_PORT": "9876",
        "LOG_LEVEL": "warn"
      }
    }
  }
}

本地验证设置示例：

{
  "inputs": [],
  "servers": {
    "blender-mcp": {
      "type": "stdio",
      "command": "/home/mackson/.config/nvm/versions/node/v25.9.0/bin/node",
      "args": [
        "/home/mackson/Documents/workspace/antigravity-blender-mcp/src/mcp-server/dist/index.js"
      ],
      "env": {
        "BLENDER_HOST": "127.0.0.1",
        "BLENDER_PORT": "9876",
        "LOG_LEVEL": "warn"
      }
    }
  }
}

编辑后 mcp.json，跑 开发者：重新加载窗口 在VSCode中或重新启动VSCode。

测试提示：

Check Blender connection status using blender-mcp

创建提示示例：

Use blender-mcp to create a red metallic cube named Codex_Test_Cube in Blender.

反重力IDE

反重力MCP配置使用 mcpServers 对象。

配置文件：

窗户： C:\Users\{username}\.gemini\antigravity\mcp_config.json
macOS/Linux： ~/.gemini/antigravity/mcp_config.json

添加以下配置：

{
  "mcpServers": {
    "blender-mcp": {
      "command": "node",
      "args": ["C:/FULL/PATH/TO/blender-mcp-v2/src/mcp-server/dist/index.js"],
      "env": {
        "BLENDER_HOST": "127.0.0.1",
        "BLENDER_PORT": "9876"
      }
    }
  }
}

替换 C:/FULL/PATH/TO/ 你的实际路径。使用正斜杠 / 甚至在Windows上。

重新启动Antigravity IDE以加载MCP服务器。

WSL用户：服务器可以自动检测Windows主机IP(172.x.x.x).你只需要硬编码 BLENDER_HOST 如果自动检测失败。

验证

验证MCP服务器是否启动

cd src/mcp-server
timeout 3s node dist/index.js

您应该看到服务器初始化和注册工具。如果命令超时，对于长时间运行的stdio服务器来说这是正常的。

通过MCP验证搅拌机连接

在Blender打开且MCP插件运行的情况下：

cd src/mcp-server
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"DRAFT-2025-v3","capabilities":{},"clientInfo":{"name":"manual-check","version":"1.0.0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"status","arguments":{}}}' \
| LOG_LEVEL=error timeout 8s node dist/index.js

预期响应内容：

{
  "connected": true,
  "version": {
    "bl": "5.1.1",
    "addon": "2.1.0",
    "sc": "Scene"
  }
}

用法示例

基本对象创建

Create a red metallic cube in Blender

带蓝图的复杂模型

Create a cyberpunk building with neon signs

人工智能辅助雕刻

Take that sphere and add horns, make it look like a demon head

过程生成

Generate a low-poly tree for my game scene

完整工作流程

Create an AWP sniper rifle, low poly style, optimize for mobile, export as GLB

建筑

┌─────────────────────────────────────────────────────────────────┐
│                                                                  │
│  Antigravity / VSCode Codex / Any MCP Client                    │
│         │                                                        │
│         │ stdio (MCP Protocol)                                  │
│         ▼                                                        │
│  TypeScript MCP Server (17 tools)                               │
│         │                                                        │
│         │ WebSocket (ws://127.0.0.1:9876)                       │
│         ▼                                                        │
│  Python Addon (mcp_connector_v2.py)                             │
│         │                                                        │
│         │ bpy (Blender Python API)                              │
│         ▼                                                        │
│  Blender 4.x / 5.x                                               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

项目结构

blender-mcp-v2/
├── src/
│   ├── mcp-server/              # TypeScript MCP server
│   │   ├── src/
│   │   │   ├── index.ts         # Entry point
│   │   │   ├── server.ts        # MCP server + tool registration
│   │   │   ├── bridge/          # WebSocket client to Blender
│   │   │   ├── tools/           # All 17 tools
│   │   │   └── utils/           # Logger, config
│   │   ├── dist/                # Compiled JS (after build)
│   │   └── package.json
│   └── blender-addon/
│       └── mcp_connector_v2.py  # Blender addon (install this)
└── README.md

发展

构建

cd src/mcp-server
npm run build

观看模式

npm run dev

测试连接

cd src/mcp-server
node verify_connection.js

如果您在受限制的沙盒中运行，本地网络调用可能会失败 EPERM在这种情况下，从正常终端或MCP客户端进程进行测试。

故障排除

“连接失败”错误

确保Blender正在运行
检查Blender首选项中是否启用了MCP插件
点击 启动服务器 在MCP面板中
验证状态是否显示“正在运行”

工具“无响应”

检查Blender系统控制台是否有错误
验证WebSocket端口是否为9876
尝试重新启动Blender和MCP客户端

“无效路径”错误

使用正斜杠 / 在MCP配置文件中，甚至在Windows上
使用完整的绝对路径，而不是相对路径
在VSCode中，更喜欢完整路径 node 从以下位置使用Node时 nvm

插件未在Blender中显示

确保您已安装 src/blender-addon/mcp_connector_v2.py （不是文件夹）
检查Blender版本是否为4.0+
看进去 Edit → 偏好→ 附加组件 并搜索“MCP”

VSCode不显示服务器

确认配置文件是有效的JSON。
确认VSCode使用 servers，不是反重力的 mcpServers.
跑 开发者：重新加载窗口 编辑后 mcp.json.
如果服务器立即退出，请检查VSCode MCP日志。

本地连接失败 `EPERM`

一些沙盒环境会阻止本地网络套接字。MCP服务器可能会启动并列出工具，但调用Blender可能会失败，原因如下：

connect EPERM 127.0.0.1:9876

在沙盒外运行MCP客户端或验证命令，或授予本地网络权限。

“连接被拒绝”（WSL用户）

确保Windows防火墙允许 blender.exe 或 python.exe 以接收连接。
插件必须说 ws://0.0.0.0:9876如果它说 127.0.0.1，重新安装最新插件。
您可以使用提供的脚本验证连接：
```
cd src/mcp-server
node verify_connection.js
```

专为

本项目专为以下目的而设计：

反重力IDE -原始目标环境。
VSCode/Codex -通过VSCode MCP配置和stdio MCP调用进行验证。
任何MCP客户端 -兼容的客户端可以启动 dist/index.js 超过stdio。
快速3D原型制作 -创建游戏资产、架构概念、场景模型和导出。

许可证

MIT许可证-您可以自由使用、修改和分发。

学分

最初是为Antigravity IDE生态系统开发的，然后为包括VSCode/Cox在内的标准MCP客户端进行了记录和验证。

特别感谢Blender和MCP社区。