UnrealMCP Plugin

Un complemento no oficial de Unreal Engine que actúa como servidor MCP, permitiendo que herramientas de IA controlen el motor de forma remota.

GitHub
10
Prueba este MCPPatrocinado

Documentación

UnrealMCP Plugin

REPOSITORIO MUY EN DESARROLLO

Estoy trabajando en añadir más herramientas ahora y limpiando el código base, planeo permitir una fácil extensión de herramientas fuera del plugin principal

Esto es muy trabajo en progreso, y necesito limpiar muchas cosas!!!!!

Además, solo uso Windows, así que no sé cómo se configuraría esto para mac/unix

Resumen

UnrealMCP es un plugin no oficial de Unreal Engine diseñado para controlar Unreal Engine con herramientas de IA. Implementa un Protocolo de Control de Máquina (MCP) dentro de Unreal Engine, permitiendo que sistemas de IA externos interactúen y manipulen el entorno de Unreal programáticamente.

Solo aprendí sobre MCP hace unos días, así que no estoy muy familiarizado con él, todavía estoy aprendiendo, así que las cosas pueden ser un poco toscas inicialmente. Lo he implementado usando https://github.com/ahujasid/blender-mcp como referencia, que depende de Claude for Desktop. Ahora funciona tanto con Claude for Desktop como con Cursor. Si experimentas con otros modelos, ¡házmelo saber!

⚠️ AVISO

Este plugin permite que agentes de IA modifiquen directamente tu proyecto de Unreal Engine. Aunque puede ser una herramienta poderosa, también conlleva riesgos:

  • Los agentes de IA pueden hacer cambios inesperados en tu proyecto
  • Los archivos podrían ser eliminados o modificados accidentalmente
  • La configuración del proyecto podría ser alterada
  • Los activos podrían ser sobrescritos

MEDIDAS DE SEGURIDAD IMPORTANTES:

  1. Usa siempre control de versiones (como Git o Perforce) con tu proyecto
  2. Haz copias de seguridad regulares de tu proyecto
  3. Prueba el plugin en un proyecto separado primero
  4. Revisa los cambios antes de confirmarlos

Al usar este plugin, reconoces que:

  • Eres el único responsable de cualquier cambio realizado en tu proyecto
  • El autor del plugin no es responsable de ningún daño, pérdida de datos o problemas causados por agentes de IA
  • Usas este plugin bajo tu propio riesgo

Características

  • Implementación de servidor TCP para control remoto de Unreal Engine
  • Protocolo de comandos basado en JSON para integración de herramientas de IA
  • Integración de interfaz de editor para acceso fácil a la funcionalidad MCP
  • Capacidades completas de manipulación de escena
  • Scripts de Python complementarios para interacción del lado del cliente

Hoja de ruta

Estas son las ideas que tengo para el desarrollo a partir del 14/03/2025 No estoy seguro de qué es posible todavía, en teoría cualquier cosa, pero depende de qué tan bueno sea el LLM integrado para utilizar estas herramientas.

  • Operaciones básicas funcionando
  • Python funcionando
  • Materiales
  • Extensiones de usuario (en progreso)
  • Herramientas de activos
  • Blueprints
  • Niagara VFX
  • Metasound
  • Landscape (podría esperar porque Epic ha mencionado que van a actualizar las herramientas de landscape)
  • Herramientas de modelado
  • PCG

Requisitos

  • Unreal Engine 5.5 (solo he probado en esta versión, puede funcionar con versiones anteriores, pero sin soporte oficial)
  • Entorno de desarrollo C++ configurado para Unreal Engine
  • Python 3.7+ para scripting del lado del cliente
  • Modelo para ejecutar los comandos, en las pruebas he estado usando Claude for Desktop https://claude.ai/download

Requisitos previos para ejecutar

  • Instalación de Unreal Editor (probado con 5.3, pero debería funcionar en 5.0+)
  • Python 3.7+ (Esto puede ejecutarse con tu instalación de Python existente)
  • LLM compatible con MCP (Claude for Desktop, Cursor, etc.)
  • Configuración: ejecuta setup_unreal_mcp.bat en la carpeta MCP según las instrucciones en MCP/README_MCP_SETUP.md

Inicio rápido para usuarios de Cursor

Si quieres usar UnrealMCP con Cursor, sigue estos sencillos pasos:

  1. Clona o descarga este repositorio como un zip
  2. Crea un nuevo proyecto de Unreal, o abre uno existente
  3. Crea una carpeta "Plugins" en el directorio de tu proyecto si no existe
  4. Descomprime o copia este repositorio en la carpeta Plugins
  5. Ejecuta setup_cursor_mcp.bat en la carpeta MCP
  6. Abre tu proyecto de Unreal y habilita el plugin en Edit > Plugins (si no está habilitado)
  7. Inicia Cursor y pídele que trabaje con tu proyecto de Unreal

¡Eso es todo! El script de configuración configurará automáticamente todo lo necesario para la integración con Cursor.

Instalación

  1. Clona o descarga este repositorio como un zip
  2. Crea un nuevo proyecto de Unreal, o abre uno existente
  3. Crea una carpeta "Plugins" en el directorio de tu proyecto si no existe
  4. Descomprime o copia este repositorio en la carpeta Plugins
  5. Configura MCP
    • Ejecuta el script setup_unreal_mcp.bat en la carpeta MCP (ver MCP/README_MCP_SETUP.md para detalles)
    • Esto configurará Python y tu asistente de IA (Claude for Desktop o Cursor)
  6. Abre tu proyecto de Unreal, el plugin debería estar disponible en el menú Plugins
  7. Si no, habilita el plugin en Edit > Plugins
  8. Elige tu asistente de IA preferido:
    • Para Claude for Desktop: sigue las instrucciones en la sección "Con Claude for Desktop" a continuación
    • Para Cursor: sigue las instrucciones en la sección "Con Cursor" a continuación

Con Claude for Desktop

Necesitarás encontrar tu directorio de instalación de Claude for Desktop. Encuentra claude_desktop_config.json y añade una entrada para que se vea así:

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "unreal": {
            "command": "C:/path/to/your/project/Plugins/UnrealMCP/MCP/run_unreal_mcp.bat",
            "args": []
        }
    }
}

Alternativamente, el script unreal_mcp_setup.bat debería hacer esto por ti.

Para encontrar la ruta a tu instalación de Claude for Desktop, puedes ir a configuración y hacer clic en 'Edit Config' Esto suele estar en

C:\Users\USERNAME\AppData\Roaming\Claude

Con Cursor

Cursor debería configurarse automáticamente si has ejecutado el script de configuración con la opción de Cursor. Si necesitas configurarlo manualmente:

Windows: %APPDATA%\Cursor\User\settings.json

Añade o actualiza la configuración con:

{
    "mcp": {
        "enabled": true,
        "servers": {
            "unreal": {
                "command": "C:/path/to/your/project/Plugins/UnrealMCP/MCP/run_unreal_mcp.bat",
                "args": []
            }
        }
    }
}

Pruebas

Una vez que todo esté configurado, necesitas lanzar el editor de Unreal. Nota: No hay que iniciar ni configurar nada más para ejecutar el puente MCP, se ejecutará cuando sea necesario.

Abre Claude for Desktop o Cursor, asegúrate de que las herramientas se hayan habilitado correctamente, pide a tu asistente de IA que trabaje en Unreal.

Aquí tienes algunos ejemplos de prompts para probar:

  • "¿Qué actores hay en el nivel actual?"
  • "Crea un cubo en la posición (0, 0, 100)"
  • "Lista los comandos disponibles que puedo usar con Unreal Engine"

Uso

En Unreal Editor

Una vez que el plugin esté habilitado, encontrarás los controles MCP en el botón de la barra de herramientas del editor. image

image

El servidor TCP se puede iniciar/detener desde aquí. Revisa el registro de salida bajo el filtro de registro LogMCP para obtener información adicional.

Una vez que el servidor esté confirmado y funcionando desde el editor. Abre Claude for Desktop, asegúrate de que las herramientas se hayan habilitado correctamente, pide a Claude que trabaje en Unreal.

Actualmente solo se admiten operaciones básicas: crear objetos, modificar sus transformaciones, obtener información de la escena y ejecutar scripts de Python. Claude comete muchos errores con Python de Unreal, ya que creo que no hay muchos ejemplos para ello, pero déjalo correr y normalmente lo resolverá. Me gustaría mucho mejorar este aspecto de cómo funciona, pero es fruta de bajo esfuerzo para añadir funcionalidad a Unreal.

Integración del lado del cliente

Usa los scripts de Python proporcionados en el directorio MCP para conectarte y controlar tu instancia de Unreal Engine:

from unreal_mcp_client import UnrealMCPClient

# Connect to the Unreal MCP server
client = UnrealMCPClient("localhost", 13377)

# Example: Create a cube in the scene
client.create_object(
    class_name="StaticMeshActor",
    asset_path="/Engine/BasicShapes/Cube.Cube",
    location=(0, 0, 100),
    rotation=(0, 0, 0),
    scale=(1, 1, 1),
    name="MCP_Cube"
)

Referencia de comandos

El plugin admite varios comandos para la manipulación de escenas:

  • get_scene_info: Obtener información sobre la escena actual
  • create_object: Generar un nuevo objeto en la escena
  • delete_object: Eliminar un objeto de la escena
  • modify_object: Cambiar propiedades de un objeto existente
  • execute_python: Ejecutar comandos de Python en el entorno de Python de Unreal
  • Y más por venir...

Consulta la documentación en el directorio Docs para una referencia completa de comandos.

Consideraciones de seguridad

  • El servidor MCP acepta conexiones de cualquier cliente por defecto
  • Limita la exposición del servidor a localhost para desarrollo
  • Valida todos los comandos entrantes para prevenir ataques de inyección

Solución de problemas

  • Asegúrate de que Unreal Engine esté ejecutándose con el plugin MCP.
  • Revisa los registros en Claude for Desktop para ver la salida de stderr.
  • Contacta en el discord, acabo de crearlo, pero lo revisaré periódicamente Discord (Dreamatron Studios): https://discord.gg/abRftdSe

Estructura del proyecto

  • Source/UnrealMCP/: Implementación principal del plugin
    • Private/: Archivos de implementación interna
    • Public/: Archivos de cabecera públicos
  • Content/: Activos del plugin
  • MCP/: Scripts de cliente de Python y ejemplos
  • Resources/: Iconos y otros recursos

Licencia

Licencia MIT

Copyright (c) 2025 kvick

Se concede permiso, de forma gratuita, a cualquier persona que obtenga una copia de este software y de los archivos de documentación asociados (el "Software"), para tratar en el Software sin restricción, incluidos, sin limitación, los derechos de usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y para permitir a las personas a quienes se les proporcione el Software que lo hagan, sujeto a las siguientes condiciones:

El aviso de copyright anterior y este aviso de permiso deberán incluirse en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO PERO NO LIMITADO A LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE CUALQUIER RECLAMO, DAÑO U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRA MANERA, QUE SURJA DE, FUERA O EN CONEXIÓN CON EL SOFTWARE O EL USO U OTROS TRATOS EN EL SOFTWARE.

Créditos

¡Gracias a los probadores!!!

Contribuciones

Las contribuciones son bienvenidas, pero necesitaré algo de tiempo para entender las cosas y limpiar primero, jaja