Unreal Engine MCP

Controla Unreal Engine con IA. Un servidor MCP que brinda a los asistentes de IA (como Claude y Cursor) acceso directo y programático al entorno de Unreal Engine para manipular escenas, generar objetos y ejecutar comandos.

GitHub
29
Prueba este MCPPatrocinado

Documentación

unreal-mcp

Unreal MCP Hero Demo

Un servidor MCP que permite a los agentes de IA (Claude, Cursor) controlar y manipular directamente Unreal Engine.

Este servidor permite a Claude (o cualquier cliente MCP) leer y editar Blueprints de Unreal Engine 5.6/5.8 directamente, sin gastar tu ventana de contexto en el JSON crudo del motor, y sin necesitar nada más que una instalación estándar de Epic Games Launcher.

Architecture

El problema que esto resuelve

Si has intentado apuntar un asistente de IA a un proyecto real de Unreal, te has topado con esto: los Blueprints no caben en una ventana de contexto. Un solo grafo volcado como datos crudos del motor es enorme, así que o el modelo nunca ve suficiente del proyecto para tener contexto real, o gastas la mayor parte de tu presupuesto re-explicando lo que ya existe cada vez que abres una conversación nueva.

Este proyecto está construido alrededor de una idea: el modelo nunca debería recibir un volcado crudo del motor. Cada salto entre el Unreal Editor y Claude compacta los datos: lecturas por niveles, ediciones basadas en diffs, y un índice persistente que se construye una vez y se actualiza incrementalmente en lugar de re-escaniarse en cada pregunta.

Cómo funciona

Dos piezas:

  • UnrealMCPBridge es un plugin de editor en C++ que se ejecuta dentro de UnrealEditor.exe y expone una interfaz TCP local a través de las APIs propias del motor Kismet2/EdGraph/AssetRegistry. Construido contra una instalación estándar del launcher: no se necesita código fuente del motor para compilarlo ni ejecutarlo.
  • mcp-server es un servidor MCP en Node/TypeScript que traduce las llamadas de herramientas MCP en solicitudes al puente, y se encarga de mantener cada respuesta barata: nombres de campos compactos, tamaños de resultados limitados, y sin re-serializar datos verbosos del motor textualmente.

Consulta ARCHITECTURE.md para el diseño completo.

Qué hace diferente a este

Ya existen varios proyectos MCP de Unreal en GitHub, y a partir de UE 5.8 Epic incluye su propio plugin MCP experimental de primera parte (solo 5.8, opcional, requiere habilitar manualmente un "Editor Toolset"). Vale la pena ser directo sobre en qué difiere realmente este proyecto, en lugar de simplemente afirmar que es "mejor":

  • Construido alrededor de la lectura, no solo de la escritura. La mayoría de los proyectos existentes son fuertes creando y manipulando Blueprints desde un prompt, pero no abordan lo que ocurre cuando el modelo necesita entender un proyecto grande ya construido primero. La lectura es aquí un ciudadano de primera clase: resúmenes por niveles antes del detalle completo, IDs de nodos que puedes referenciar sin volver a buscar.
  • Un índice de proyecto persistente, actualizado incrementalmente. El puente indexa Blueprints, funciones, variables y referencias entre activos una vez, lo guarda en caché en disco, y lo actualiza a partir de los delegados de AssetRegistry mientras editas, en lugar de re-escanear el proyecto en cada consulta. find_references responde "qué usa realmente este Blueprint" sin que el modelo tenga que enumerar el proyecto por sí mismo.
  • Un enganche opcional de modelo local para la indexación. Si apuntas UNREAL_MCP_LOCAL_LLM_URL a un modelo local (Ollama o cualquier cosa compatible con OpenAI), los resúmenes de indexación se generan allí en lugar de gastar los tokens de Claude en trabajo mecánico de escaneo. Totalmente opcional. El índice funciona sin ello.
  • Compatible con 5.6 y 5.8 desde un mismo código base, mientras que varios proyectos existentes están fijados a una única versión del motor.

El estudio completo del ecosistema existente (licencias, arquitecturas, qué hace bien cada uno) está en docs/COMPETITIVE_LANDSCAPE.md.

Estado

Esto se está construyendo y verificando en público, hito a hito. El documento de estado de cada hito está escrito con honestidad, incluyendo qué está compilado/probado frente a lo que aún no está verificado:

  • Hito 1: introspección de Blueprints de solo lectura: compila y se ejecuta contra una instalación real de UE 5.8; protocolo MCP verificado de extremo a extremo.
  • Hito 2: crear/editar grafos de Blueprint: crear Blueprints, añadir nodos, conectar pines, añadir variables, compilar con informes de errores estructurados.
  • Hito 3: índice de proyecto persistente, búsqueda, referencias: índice actualizado incrementalmente (respaldado por AssetRegistry, con caché en disco), search_project, find_references, get_project_overview, enriquecimiento opcional con modelo local para los resultados de búsqueda.
  • Hito 4: soporte para UE 5.6: verificado en vivo en 5.6, 21 de 21 comprobaciones superadas, y publicado. El código fuente del plugin no necesita ningún cambio entre las dos versiones del motor.
  • Hito 5: catálogo de referencia de nodos/funciones: unreal_find_node y unreal_get_node_signature, leyendo la superficie real invocable por Blueprint del motor en ejecución mediante reflexión (12 402 funciones en 5.6, 15 775 en 5.8, construido en ~0,1 s). unreal_add_node ahora responde a un nombre de función incorrecto con didYouMean coincidencias cercanas en lugar de un callejón sin salida.

Los cinco hitos están verificados en compilación, verificados en protocolo, y verificados en vivo en ambas versiones del motor. Consulta docs/LIVE_VERIFICATION.md para la sesión en 5.8 contra un proyecto real de ~20 Blueprints y docs/UE56_STATUS.md para la de 5.6: lecturas que devuelven datos reales correctos, un ciclo completo de escritura crear/cablear/compilar/guardar, y la confirmación de que el índice de proyecto incremental se mantiene realmente fresco sin reiniciar el editor (la afirmación central de M3).

Ambas sesiones en vivo demostraron su valor al detectar un error real que ninguna cantidad de compilación o pruebas de protocolo habría sacado a la luz. En 5.8 fue add_node duplicando un nodo de evento anulado ya presente. En 5.6 fue .uplugin fijando EngineVersion a 5.8.0: todas las comprobaciones de compilación pasaban porque UnrealBuildTool ignora ese campo, pero el cargador de plugins en tiempo de ejecución lo respeta, así que el editor se detenía en un diálogo modal de incompatibilidad y el puente nunca arrancaba.

Desde entonces, todo eso también se ha ejercitado en vivo: remove_node y VariableGet están cubiertos por las suites de IDs de nodo y flujo de control, y add_node ahora coloca Branch, Sequence, Cast, y macros de la biblioteca estándar (ForEachLoop, WhileLoop, ...) directamente, verificado construyendo y compilando un grafo condicional real solo a través del puente. Los IDs de nodo son GUID persistentes, y cada escritura se puede deshacer con Ctrl+Z bajo una transacción "MCP:" con nombre. Aún pendiente: los tipos de nodo CustomEvent/VariableSet no han tenido una comprobación en vivo dedicada, y el catálogo M5 cubre nodos respaldados por UFunction; los tipos nativos UK2Node se colocan mediante los valores dedicados de nodeType en lugar de descubrirse a través de unreal_find_node.

Inicio rápido (instalación en 3 pasos)

Asegúrate de tener Node.js 18+ y un proyecto de UE 5.6 / 5.8.

1. Instalar el plugin de Unreal

La vía más fácil: descarga el plugin precompilado para tu versión del motor y descomprímelo en la carpeta Plugins/UnrealMCPBridge/ de tu proyecto, para que nunca tengas que compilarlo tú mismo:

O compílalo tú mismo copiando la carpeta del plugin UnrealMCPBridge al directorio Plugins/ de tu proyecto de Unreal:

# macOS / Linux
mkdir -p "/path/to/YourProject/Plugins" && cp -r UnrealMCPBridge "/path/to/YourProject/Plugins/"

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "C:\path\to\YourProject\Plugins"; Copy-Item -Recurse UnrealMCPBridge "C:\path\to\YourProject\Plugins\"

Nota: Reconstruye/abre tu proyecto de Unreal para compilar el plugin y asegúrate de que esté habilitado en el editor.

2. Compilar el servidor MCP

Instala las dependencias de node y compila el código base de TypeScript:

cd mcp-server && npm install && npm run build

3. Registrar el servidor

Conecta el servidor a tu cliente MCP usando la ruta absoluta a mcp-server/dist/index.js:

Claude Code:

claude mcp add unreal -- node "/path/to/unreal-mcp/mcp-server/dist/index.js"

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "unreal": {
      "command": "node",
      "args": ["/path/to/unreal-mcp/mcp-server/dist/index.js"]
    }
  }
}

Una vez registrado, abre tu proyecto en el Unreal Editor y verifica la conexión mediante unreal_ping.

Para más opciones de configuración y detalles, consulta mcp-server/README.md.

Contribuciones

Las incidencias y pull requests son bienvenidas. Este proyecto es joven y se mueve rápido, así que revisa los documentos de estado anteriores antes de asumir que algo funciona de extremo a extremo.

Licencia

MIT. Consulta LICENSE.