Blender-Mind-MCP (Modelado 3D automatizado con IA y puente para Blender)

Un servidor Model Context Protocol (MCP) de producción y un ecosistema de complemento para Blender orientados al modelado 3D automatizado, la generación de activos procedurales, la creación de shaders y la inspección multimodal del viewport.

🏗️ Antecedentes e inspiración arquitectónica

Este proyecto incorpora lecciones arquitectónicas y referencias de los principales proyectos de IA para Blender en GitHub (como ahujasid/blender-mcp y djeada/blender-mcp-server):

1. Despacho seguro de hilos en el hilo principal: la API C de Python de Blender (bpy) no es thread-safe. Como se detectó en las auditorías de incidencias de la comunidad, ejecutar llamadas bpy desde hilos de escucha de sockets en crudo provoca corrupción de memoria y fallos de segmentación. Nuestro complemento para Blender utiliza una queue.Queue thread-safe junto con bpy.app.timers para garantizar que todas las modificaciones de la escena se ejecuten estrictamente en el bucle principal de renderizado/UI de Blender.

2. Aislamiento de pasos de deshacer: toda ejecución de código de IA se envuelve con bpy.ops.ed.undo_push(), lo que permite deshacer sin fricciones con Ctrl+Z dentro de Blender.

3. Captura multimodal de viewport: utiliza renderizado OpenGL fuera de pantalla (bpy.ops.render.opengl) para devolver capturas de pantalla PNG codificadas en Base64 del viewport 3D directamente a modelos de visión multimodal.

4. Arquitectura hexagonal (puertos y adaptadores): desacopla la generación pura de geometría 3D de los controladores físicos, con soporte tanto para conexiones por socket en vivo (127.0.0.1:9876) como para procesamiento por lotes en CLI sin interfaz (blender -b) y simulación offline de binarios glTF procedurales.

Related MCP server: Blender MCP Server

📦 Estructura del proyecto

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

🚀 Inicio rápido

1. Instalar el complemento en Blender

1. Abre Blender (3.6+ o 4.x).

2. Ve a Edición > Preferencias > Complementos > Instalar...</ (o a la flecha "Instalar desde el disco" en 4.2+).

3. Selecciona addon/blender_mcp_addon.py.

4. Activa Development: Blender MCP Bridge.

5. En el viewport 3D, pulsa N para abrir la barra lateral, haz clic en la pestaña Blender MCP y haz clic en Start MCP Server.

2. Configurar el cliente MCP (Antigravity / Claude / Codex)

Añade la siguiente configuración a tu MCP del proyecto o global (.mcp.json):

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

🛠️ Las 10 herramientas principales de MCP

🧪 Verificación por niveles de verdad

npm test

Ejecuta las 6 suites de pruebas en los 4 niveles de la escalera de verdad:

• L1 Unit: modelado de dominio 100 % puro y comprobaciones AST del synthesizer de código Python.

• L2 Contract: definiciones de esquema y verificación de despacho de las 10 herramientas.

• L3 Integration: validación de la cabecera del binario glTF v2 (0x46546C67) y de la estructura de la malla OBJ.

• L3 Integration: prueba de bucle local (loopback) cliente-servidor mediante socket TCP en vivo en 127.0.0.1:9899.

• L4 E2E: prueba de ida y vuelta de la tubería JSON-RPC en stdio en vivo.