MCP de Unreal Blender

Unreal-Blender MCP es un servidor unificado para controlar Blender y Unreal Engine a través de agentes de IA utilizando el enfoque MCP (Protocolo de control de máquina).

Descripción general

Este proyecto amplía el marco blender-mcp para incluir soporte para Unreal Engine, permitiendo que agentes de IA como Claude y ChatGPT controlen simultáneamente ambas plataformas a través de una única interfaz.

Información del submódulo

Este proyecto incluye blender-mcp como submódulo de Git. Al clonar el repositorio, use los siguientes comandos:

Características

• Control unificado : servidor MCP único para controlar tanto Blender como Unreal Engine
• Integración del agente de IA : diseñado para funcionar con Claude, ChatGPT y otros asistentes de IA
• Características de Blender : Conserva todas las funciones de Blender-mcp, incluidas:
  • Manipulación de escenas
  • Creación y edición de objetos
  • Gestión de materiales
  • Integración de activos de PolyHaven
  • Generación de modelos de Rodin en Hyper3D
• Características de Unreal Engine :
  • Creación y gestión de niveles
  • Importación de activos
  • Ejecución de código Python
  • Manipulación de escenas
• Estructura de extensión : amplíe fácilmente tanto el complemento como el servidor de Blender mientras mantiene la compatibilidad con las actualizaciones ascendentes

Arquitectura

El sistema consta de tres componentes principales:

1. Servidor MCP : centro central que se comunica con agentes de IA a través de SSE (eventos enviados por el servidor) en el puerto 8000
2. Complemento de Blender : servidor de sockets dentro de Blender en el puerto 8400 (estándar) o 8401 (extendido)
3. Complemento de Unreal : servidor HTTP dentro de Unreal Engine en el puerto 8500

Estructura de extensión

Este proyecto utiliza un enfoque de extensión para mantener la compatibilidad con los cambios anteriores:

• Extensión complementaria de Blender : extiende el BlenderMCPServer original manteniendo intacto el código original
• Extensión del servidor : mejora el servidor original con herramientas adicionales e integración con Unreal Engine
• Herramientas de interfaz : proporciona utilidades para instalar, configurar y ejecutar extensiones

Este enfoque permite actualizaciones fáciles de los proyectos originales sin conflictos de código.

Guía de instalación y configuración paso a paso

Prerrequisitos

• Python 3.10 o posterior
• Blender 3.0 o posterior
• Unreal Engine 5.0 o posterior
• Administrador de paquetes uv (instálelo con pip install uv si no lo tiene)

1. Clonar el repositorio

2. Configurar el entorno de Python

3. Instalar el complemento Blender

Elija UNA de las siguientes opciones:

Opción A: Complemento estándar (Blender-mcp original)

1. Abra Blender
2. Vaya a Editar > Preferencias > Complementos
3. Haga clic en el botón "Instalar..."
4. Busque y seleccione el archivo blender-mcp/addon.py
5. Habilite el complemento "Interfaz: Blender MCP" (marque la casilla)

Opción B: Complemento extendido (con funciones adicionales)

1. Ejecute el script de instalación de la extensión:
   python -c "from src.unreal_blender_mcp.blender_addon import BlenderAddonManager; BlenderAddonManager().install_to_blender(force=True)"
2. Abra Blender
3. Vaya a Editar > Preferencias > Complementos
4. Busque y habilite el complemento "Interfaz: Extended Blender MCP" (marque la casilla)

4. Instalar el complemento Unreal Engine

1. Localice la carpeta UEPythonServer en este proyecto
2. Copia la carpeta completa al directorio Plugins de tu proyecto Unreal
   • Si su proyecto no tiene un directorio Plugins , cree uno
3. Inicia Unreal Engine con tu proyecto
4. Vaya a Editar > Complementos en el menú
5. Busque y habilite el complemento Python Server
6. Reinicie Unreal Engine cuando se le solicite

5. Inicie el servidor MCP

Elija UNA de las siguientes opciones:

Opción A: Servidor estándar

Opción B: Servidor Extendido (Más funciones)

6. Habilitar la conexión al servidor Blender

1. Iniciar Blender (si aún no está en ejecución)
2. En la ventana gráfica 3D, presione N para abrir el panel de la barra lateral
3. Seleccione la pestaña apropiada:
   • "BlenderMCP" (si se usa el complemento estándar)
   • "ExtBlenderMCP" (si se utiliza un complemento extendido)
4. Haga clic en el botón "Iniciar servidor"
5. Verifique que el servidor se inicie correctamente (verifique la salida de la consola)

7. Verificar la conexión de Unreal Engine

1. Con Unreal Engine ejecutándose y el complemento habilitado
2. El servidor Python debería iniciarse automáticamente
3. Verifique el registro de salida (Ventana > Herramientas para desarrolladores > Registro de salida) para ver si hay mensajes
4. El complemento Unreal ahora debería estar listo para recibir comandos

8. Conectar un agente de IA

Opción A: Integración con Claude para escritorio

Agregue lo siguiente a la configuración de Claude for Desktop:

Reemplace /path/to/ con la ruta de su proyecto actual.

Opción B: Integrar con Cursor

1. Abrir configuración del cursor
2. Navegar a la sección MCP
3. Agregue los siguientes comandos:
   • Servidor estándar: uvx unreal-blender-mcp
   • Servidor extendido: python /path/to/unreal-blender-mcp/run_extended_server.py Reemplace /path/to/ con la ruta de su proyecto actual.

Opción C: Integración con otras herramientas de IA

Consulta la documentación de tu herramienta de IA para integrarla con servidores MCP y dirígela a:

• URL del servidor MCP: http://localhost:8000 (o puerto personalizado si se especifica)

9. Prueba del sistema

Una vez que todos los componentes estén en ejecución:

1. Utilice su agente de IA para interactuar con Blender pidiéndole que:
   • Crea un cubo o esfera simple
   • Modificar las propiedades del objeto
   • Crear materiales
2. Utilice su agente de IA para interactuar con Unreal Engine pidiéndole que:
   • Crear un nuevo nivel
   • Colocar activos
   • Modificar las propiedades de la escena
3. Pruebe operaciones más complejas que involucren ambas plataformas trabajando juntas

Solución de problemas

Si encuentra problemas:

1. Compruebe que todos los servidores estén en ejecución (MCP, Blender, Unreal)
2. Verificar que las configuraciones del puerto coincidan (predeterminado: 8000 para MCP, 8400/8401 para Blender, 8500 para Unreal)
3. Verifique las salidas de la consola para ver si hay mensajes de error
4. Reinicie los componentes en el orden correcto: primero el servidor MCP, luego Blender y luego Unreal Engine

Para obtener información más detallada sobre el desarrollo y la ampliación del sistema, consulte el documento del proyecto y el directorio de flujo de trabajo .

Comparación: Estándar vs. Extendido

Elija el servidor estándar para la funcionalidad básica o el servidor extendido para funciones avanzadas.

Desarrollo

Consulte el documento del proyecto y el directorio de flujo de trabajo para obtener información detallada sobre el desarrollo.

Para ampliar este proyecto:

• Para agregar nuevas funciones complementarias de Blender: Modifique src/unreal_blender_mcp/blender_addon/extended_addon.py
• Para agregar nuevas herramientas de servidor: Modifique src/unreal_blender_mcp/server_extension/extended_server.py

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Expresiones de gratitud

• Este proyecto se basa en blender-mcp de Siddharth Ahuja.

Desarrollos futuros

Se planean las siguientes mejoras para futuras versiones:

API estructurada de Unreal Engine

Actualmente, la comunicación con Unreal Engine se basa principalmente en la ejecución directa de código Python. Una mejora prevista es implementar una API estructurada similar a la integración con Blender:

• Crear funciones predefinidas para operaciones comunes de Unreal Engine
• Implementar un manejo y validación de errores adecuados
• Mejorar la seguridad limitando el alcance de ejecución
• Mejorar la estabilidad y la previsibilidad de las operaciones
• Mantener la compatibilidad con versiones anteriores mientras se agrega estructura

Esta mejora creará una experiencia más consistente en ambos motores y mejorará la fiabilidad general del sistema. Consulte la documentación del flujo de trabajo para obtener más detalles sobre este desarrollo planificado.