Unreal-Blender MCP

Un servidor unificado para controlar Blender y Unreal Engine mediante agentes de IA.

GitHub
18
Prueba este MCPPatrocinado

Documentación

Unreal-Blender MCP

Unreal-Blender MCP es un servidor unificado para controlar tanto Blender como Unreal Engine mediante agentes de IA utilizando el enfoque MCP (Machine Control Protocol).

Descripción general

Este proyecto extiende el framework 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 un submódulo de Git. Al clonar el repositorio, utiliza los siguientes comandos:

# Clone with submodules
git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git

# Or clone normally and then initialize submodules
git clone https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp
git submodule update --init --recursive

Características

  • Control unificado: Un único servidor MCP para controlar tanto Blender como Unreal Engine
  • Integración con agentes de IA: Diseñado para funcionar con Claude, ChatGPT y otros asistentes de IA
  • Funciones de Blender: Conserva toda la funcionalidad de blender-mcp, incluyendo:
    • Manipulación de escenas
    • Creación y edición de objetos
    • Gestión de materiales
    • Integración de activos PolyHaven
    • Generación de modelos Hyper3D Rodin
  • Funciones 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: Extiende fácilmente tanto el addon de Blender como el servidor manteniendo la compatibilidad con las actualizaciones ascendentes

Arquitectura

El sistema consta de tres componentes principales:

  1. Servidor MCP: Centro central que se comunica con los agentes de IA mediante SSE (Server-Sent Events) en el puerto 8000
  2. Addon de Blender: Servidor de sockets dentro de Blender en el puerto 8400 (estándar) o 8401 (extendido)
  3. Plugin de Unreal: Servidor HTTP dentro de Unreal Engine en el puerto 8500
[AI Agent] <--SSE--> [MCP Server (8300)] 
                        |
                        |--HTTP--> [Blender Addon (8400)]
                        |
                        |--HTTP--> [Unreal Plugin (8500)]

Estructura de extensión

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

  • Extensión del addon 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 sencillas desde los proyectos originales sin conflictos de código.

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

Requisitos previos

  • Python 3.10 o posterior
  • Blender 3.0 o posterior
  • Unreal Engine 5.0 o posterior
  • Gestor de paquetes uv (instálalo con pip install uv si no lo tienes)

1. Clonar el repositorio

# Clone with submodules (recommended)
git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp

# Or if you already cloned without --recursive:
git clone https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp
git submodule update --init --recursive

2. Configurar el entorno de Python

# Create a virtual environment and activate it
uv venv
# On Windows:
.\venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install project dependencies
uv pip install -e .

3. Instalar el addon de Blender

Elige UNA de las siguientes opciones:

Opción A: Addon estándar (blender-mcp original)

  1. Abre Blender
  2. Navega a Editar > Preferencias > Add-ons
  3. Haz clic en el botón "Instalar..."
  4. Busca y selecciona el archivo blender-mcp/addon.py
  5. Activa el addon "Interface: Blender MCP" (marca la casilla)

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

  1. Ejecuta el script del instalador de extensiones: 
    python -c "from src.unreal_blender_mcp.blender_addon import BlenderAddonManager; BlenderAddonManager().install_to_blender(force=True)"
  2. Abre Blender
  3. Navega a Editar > Preferencias > Add-ons
  4. Busca y activa el addon "Interface: Extended Blender MCP" (marca la casilla)

4. Instalar el plugin de Unreal Engine

  1. Localiza la carpeta UEPythonServer en este proyecto
  2. Copia la carpeta completa al directorio Plugins de tu proyecto de Unreal
    • Si tu proyecto no tiene un directorio Plugins, créalo
  3. Inicia Unreal Engine con tu proyecto
  4. Navega a Editar > Plugins en el menú
  5. Busca y activa el plugin Python Server
  6. Reinicia Unreal Engine cuando se te solicite

5. Iniciar el servidor MCP

Elige UNA de las siguientes opciones:

Opción A: Servidor estándar

# Make sure your virtual environment is activated
python main.py

Opción B: Servidor extendido (más funciones)

# Make sure your virtual environment is activated
python run_extended_server.py

# Optional: Customize server options
python run_extended_server.py --host 127.0.0.1 --port 8080 --log-level DEBUG

6. Activar la conexión del servidor de Blender

  1. Inicia Blender (si no está ya en ejecución)
  2. En el viewport 3D, presiona N para abrir el panel lateral
  3. Selecciona la pestaña correspondiente:
    • "BlenderMCP" (si usas el addon estándar)
    • "ExtBlenderMCP" (si usas el addon extendido)
  4. Haz clic en el botón "Start Server"
  5. Verifica que el servidor se inicia correctamente (revisa la salida de la consola)

7. Verificar la conexión de Unreal Engine

  1. Con Unreal Engine en ejecución y el plugin activado
  2. El servidor Python debería iniciarse automáticamente
  3. Revisa el registro de salida (Ventana > Herramientas de desarrollo > Registro de salida) para ver cualquier mensaje
  4. El plugin de Unreal debería estar listo para recibir comandos

8. Conectar un agente de IA

Opción A: Integración con Claude for Desktop

Añade lo siguiente a la configuración de Claude for Desktop:

{
    "mcpServers": {
        "unreal-blender": {
            "command": "uvx",
            "args": [
                "unreal-blender-mcp"
            ]
        },
        "unreal-blender-ext": {
            "command": "python",
            "args": [
                "/path/to/unreal-blender-mcp/run_extended_server.py"
            ]
        }
    }
}

Reemplaza /path/to/ con la ruta real de tu proyecto.

Opción B: Integración con Cursor

  1. Abre la configuración de Cursor

  2. Navega a la sección MCP

  3. Añade los siguientes comandos:

    • Servidor estándar: uvx unreal-blender-mcp
    • Servidor extendido: python /path/to/unreal-blender-mcp/run_extended_server.py

    Reemplaza /path/to/ con la ruta real de tu proyecto.

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

Consulta la documentación de tu herramienta de IA para la integración con servidores MCP y apúntala a:

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

9. Probar el sistema

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

  1. Usa tu agente de IA para interactuar con Blender pidiéndole que:

    • Cree un cubo o una esfera simple
    • Modifique propiedades de objetos
    • Cree materiales

  2. Usa tu agente de IA para interactuar con Unreal Engine pidiéndole que:

    • Cree un nuevo nivel
    • Coloque activos
    • Modifique propiedades de la escena

  3. Prueba operaciones más complejas que impliquen que ambas plataformas trabajen juntas

Solución de problemas

Si encuentras problemas:

  1. Comprueba que todos los servidores estén en ejecución (MCP, Blender, Unreal)
  2. Verifica que las configuraciones de puertos coincidan (por defecto: 8000 para MCP, 8400/8401 para Blender, 8500 para Unreal)
  3. Revisa las salidas de consola para ver mensajes de error
  4. Reinicia los componentes en el orden correcto: primero el servidor MCP, luego Blender y después Unreal Engine

Para obtener información más detallada sobre el desarrollo y la extensión del sistema, consulta el Documento del proyecto y el directorio de workflow.

Comparación: Estándar vs Extendido

FunciónServidor estándarServidor extendido
Control de Blender✅✅
Control de Unreal✅✅
Comandos personalizados de Blender❌✅
Información de escena mejorada❌✅
Detección automática de funciones❌✅
Compatibilidad ascendente✅✅

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

Desarrollo

Consulta el Documento del proyecto y el directorio de workflow para obtener información detallada sobre el desarrollo.

Para extender este proyecto:

  • Para añadir nuevas funciones al addon de Blender: Modifica src/unreal_blender_mcp/blender_addon/extended_addon.py
  • Para añadir nuevas herramientas al servidor: Modifica src/unreal_blender_mcp/server_extension/extended_server.py

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.

Agradecimientos

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

Desarrollos futuros

Las siguientes mejoras están planificadas 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 planificada es implementar una API estructurada similar a la integración de Blender:

  • Crear funciones predefinidas para operaciones comunes de Unreal Engine
  • Implementar un manejo de errores y validación adecuados
  • Mejorar la seguridad limitando el ámbito de ejecución
  • Mejorar la estabilidad y previsibilidad de las operaciones
  • Mantener la compatibilidad hacia atrás mientras se añade estructura

Esta mejora creará una experiencia más coherente en ambos motores y mejorará la fiabilidad general del sistema. Consulta la documentación del workflow para más detalles sobre este desarrollo planificado.