blender-lab-mcp-client

Un cliente MCP que habla el protocolo de red real del complemento MCP oficial "Blender Lab" de Blender.org, exponiendo las mismas 27 herramientas que djeada/blender-mcp-server — pero funcionando contra blender.org/lab/mcp-server en lugar del complemento incluido de ese proyecto.

Por qué existe esto

Hay (al menos) dos proyectos "Blender + MCP" no relacionados que comparten nombre, puerto por defecto y una propuesta similar:

1. djeada/blender-mcp-server — incluye un par emparejado: su propio complemento de Blender y un cliente MCP en Python, que se comunican mediante un protocolo delimitado por nueva línea {"id", "command", "params"} / {"success", "result"} a través de localhost:9876.

2. El complemento oficial de Blender Lab (blender.org/lab/mcp-server, responsable "Blender Authors") — un proyecto completamente separado. También escucha en localhost:9876, pero solo incluye el lado del complemento. Se comunica mediante peticiones {"type": "execute", "code": ..., "strict_json": ...} delimitadas por byte nulo y respuestas {"status": "ok"|"error", "result": ...}, no tiene un despachador de comandos nombrados integrado (solo ejecuta Python crudo contra bpy) y cierra su conexión TCP después de cada petición.

Si instalas el complemento oficial de Blender Lab pero configuras un cliente MCP apuntando a djeada/blender-mcp-server (p. ej. mediante uvx blender-mcp-server), cada llamada a una herramienta falla con algo como:

Extra data: line 1 column 51 (char 50)

o, en la siguiente llamada:

Lost connection to Blender: Blender connection closed

Eso no es una conexión inestable, un proceso obsoleto ni un error de Blender — son dos protocolos no relacionados que no se entienden entre sí. El cliente de djeada envía una petición terminada en nueva línea que el complemento nunca reconoce; el complemento agota el tiempo de espera del cliente, envía un pequeño error terminado en byte nulo, y el readline() del cliente se atraganta con el byte nulo suelto inmediatamente después del objeto JSON.

Este paquete reimplementa cada una de las 27 herramientas MCP originales generando el Python bpy equivalente y enviándolo a través del protocolo real del complemento de Blender Lab, de modo que los nombres de las herramientas, los parámetros y el comportamiento siguen siendo los mismos — solo cambia el formato de red subyacente.

Instalación

1. Instala el complemento MCP oficial de Blender Lab en Blender (Editar → Preferencias → Complementos → busca "MCP", o a través de la plataforma de Extensiones) y confirma que está escuchando en 127.0.0.1:9876 (Preferencias del complemento → Iniciar servidor).

2. Instala este paquete:

   git clone https://github.com/A-to-PC/blender-lab-mcp-client.git
   cd blender-lab-mcp-client
   pip install -e .

3. Apunta tu cliente MCP a él. Para una configuración estilo mcp.json:

   {
     "servers": {
       "Blender": {
         "type": "stdio",
         "command": "blender-lab-mcp-client"
       }
     }
   }

   O ejecútalo directamente desde el código fuente sin instalarlo, mediante uv:

   {
     "servers": {
       "Blender": {
         "type": "stdio",
         "command": "uv",
         "args": ["run", "--project", "/absolute/path/to/blender-lab-mcp-client", "blender-lab-mcp-client"]
       }
     }
   }

Referencia de herramientas

Las mismas 27 herramientas que el proyecto original — consulta la referencia de herramientas de djeada/blender-mcp-server para la tabla completa (inspección de escena, manipulación de objetos, materiales, renderizado/exportación, historial, ejecución de Python, trabajos asíncronos). Los nombres y parámetros no cambian; solo el transporte subyacente es diferente.

Limitaciones conocidas

• blender_python_exec_async / blender_job_status / blender_job_cancel / blender_job_list (solo transporte bridge) se simulan como síncronos. El mecanismo real de trabajos diferidos del complemento requiere que el propio código ejecutado establezca un callable check_is_finished, lo que no es práctico de sintetizar genéricamente a partir de código arbitrario enviado. Las llamadas asíncronas contra la sesión viva de Blender en realidad se ejecutan síncronamente y se informan inmediatamente como "succeeded". Para trabajo realmente de larga duración (horneados de física, simulaciones pesadas), usa transport="headless" en su lugar — esa vía ejecuta un proceso en segundo plano blender -b separado y no se ve afectada por esta limitación.

• Una conexión por petición. El complemento cierra su socket después de cada respuesta, por lo que este cliente no puede reutilizar una conexión persistente — cada llamada a una herramienta abre una nueva conexión TCP. Esto coincide con el diseño real del complemento; no es un atajo de rendimiento que pueda "arreglarse" del lado del cliente.

• Probado contra Blender 5.2 LTS con el complemento de Blender Lab. El código auxiliar de objetos/materiales usa llamadas estándar bpy.ops.* y debería funcionar en cualquier versión reciente de Blender, pero no se ha verificado en una matriz de versiones.

Créditos

Derivado de djeada/blender-mcp-server (licencia MIT) por Adam Djellouli — la superficie de herramientas MCP (nombres, parámetros, descripciones) y el transporte de ejecución en segundo plano headless.py se mantienen sin cambios. Solo BlenderConnection de server.py y la capa de traducción de comandos a código bpy son nuevos, para apuntar al protocolo del complemento oficial de Blender Lab en lugar del complemento incluido del proyecto original.

Licencia

MIT — consulta LICENSE.