Skip to main content
Glama
xiaohai-uid

Blender-Mind-MCP

by xiaohai-uid

Blender-Mind-MCP(生产级 AI 3D 建模与 Blender 桥接)

一个生产级的 Model Context Protocol (MCP) 服务器与 Blender 插件生态系统,用于自动化 3D 建模、程序化资产生成、着色器编写以及多模态视口检查。


🏗️ 既有实现与架构启发

本项目借鉴了 GitHub 上领先的 Blender AI 项目(例如 ahujasid/blender-mcpdjeada/blender-mcp-server)的架构经验:

  1. 线程安全的主线程调度:Blender 的 Python C-API(bpy)并非线程安全。正如社区问题审计中所发现的,在原始 socket 监听线程中执行 bpy 调用会触发内存损坏和段错误。因此,本插件使用线程安全的 queue.Queue 结合 bpy.app.timers,确保所有场景修改严格在 Blender 的主渲染/GUI 循环中执行。

  2. 撤销步骤隔离:每次 AI 代码执行都会使用 bpy.ops.ed.undo_push() 包裹,从而支持在 Blender 内进行无缝的 Ctrl+Z 回滚。

  3. 多模态视口捕获:使用离屏 OpenGL 渲染(bpy.ops.render.opengl)将 3D 视口的 Base64 编码 PNG 截图直接返回给多模态视觉模型。

  4. 六边形架构(端口与适配器):将纯 3D 几何生成与物理驱动解耦,同时支持实时 Socket 连接(127.0.0.1:9876)、无头 CLI 批处理(blender -b)以及离线程序化 glTF 二进制仿真。


Related MCP server: Blender MCP Server

📦 项目结构

blender-mind-mcp/
├── addon/
│   └── blender_mcp_addon.py       # Full Blender 3.x/4.x Addon (UI Sidebar Panel, Socket Server, Viewport Capture)
├── src/
│   ├── index.ts                   # stdio JSON-RPC MCP Server entry point
│   ├── bridge/
│   │   └── socket_client.ts       # Robust TCP Socket Client with reconnect & timeout handling
│   ├── core/
│   │   └── domain/
│   │       ├── types.ts           # 3D Domain Types (Scene, Mesh, Material, Modifier, Transform)
│   │       ├── scene.ts           # Pure in-memory 3D scene graph & polygon math
│   │       └── bpy_generator.ts   # Modern Blender 4.x/3.x Python code synthesizer
│   ├── ports/
│   │   └── driver.port.ts         # BlenderDriverPort interface specification
│   ├── adapters/
│   │   ├── live_socket.adapter.ts # Live Socket Adapter (talks to active Blender GUI)
│   │   ├── blender_cli.adapter.ts # Headless CLI Adapter (talks to blender.exe)
│   │   └── mock_geometry.adapter.ts # Offline Simulation Adapter (glTF & OBJ binary synthesis)
│   └── tools/
│       └── index.ts               # 10 MCP Tools registry & dispatcher
├── tests/
│   ├── unit/                      # L1: Domain math & Python code generation
│   ├── contract/                  # L2: MCP tool schemas & argument contracts
│   ├── integration/               # L3: Binary glTF headers & TCP Socket Bridge
│   └── run_tests.ts               # Complete Truth Ladder test runner
├── package.json
└── tsconfig.json

🚀 快速开始

1. 在 Blender 中安装插件

  1. 打开 Blender(3.6+ 或 4.x)。

  2. 转到 编辑 > 偏好设置 > 插件 > 安装...(在 4.2+ 中也可点击“从磁盘安装”箭头)。

  3. 选择 addon/blender_mcp_addon.py

  4. 启用 开发:Blender MCP Bridge

  5. 在 3D 视口中按 N 打开侧边栏,点击 Blender MCP 标签,然后点击 启动 MCP 服务器

2. 配置 MCP 客户端(Antigravity / Claude / Codex)

在项目或全局 MCP 配置(.mcp.json)中添加:

{
  "mcpServers": {
    "blender": {
      "command": "node",
      "args": [
        "--disable-warning=ExperimentalWarning",
        "--experimental-strip-types",
        "C:/Users/a1691/Documents/antigravity/noble-hypatia/src/index.ts"
      ]
    }
  }
}

🛠️ 10 个核心 MCP 工具

工具名称

描述

核心能力

blender_create_primitive

创建程序化 3D 网格

cubespherecylindertorusplaneconemonkey

blender_apply_modifier

附加程序化修改器

subsurfbevelbooleanmirrorarraysolidify

blender_procedural_material

PBR 原理化 BSDF 着色器

base_colormetallicroughnesstransmission(玻璃)、emission

blender_setup_lighting

设置并调校光源

SUNPOINTSPOTAREA(功率、半径、色调)

blender_setup_camera

相机取景与镜头

locationlook_at 跟踪、以毫米为单位的 focal_length

blender_capture_viewport

视觉视口快照

向多模态 LLM 直接返回 Base64 PNG 图像

blender_export_asset

3D 模型烘焙与导出

.glb.gltf.obj.stl.fbx

blender_inspect_scene

拓扑与场景树检视

层级对象列表、多边形数量、顶点数量、修改器

blender_execute_bpy

执行原始参数 Python 代码

沙箱执行,并捕获 stdout/stderr

blender_health

系统诊断

报告当前活动驱动、端口状态和 Blender 构建版本


🧪 真值阶梯验证

npm test

在四级真值阶梯上执行全部 6 个测试套件:

  • L1 单元测试:100% 纯领域建模与 Python 代码生成器 AST 检查。

  • L2 契约测试:全部 10 个工具的模式定义与调度验证。

  • L3 集成测试:二进制 glTF v2 文件头(0x46546C67)与 OBJ 结构验证。

  • L3 集成测试:在 127.0.0.1:9899 上进行的实时 TCP Socket 双端回环测试。

  • L4 端到端测试:实时 stdio JSON-RPC 管道往返验证。

Install Server
A
license - permissive license
A
quality
C
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…

  • AI visual generation agent: multi-pipeline rendering, prompt crafting, and image composition.

  • Build and run visual creative-production workflows from your AI agent.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/xiaohai-uid/blender-mind-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server