Unreal Engine MCP

unreal-mcp

Un servidor MCP que permite a 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 JSON crudo del motor, y sin necesitar nada más que una instalación estándar de Epic Games Launcher.

El problema que resuelve

Si has intentado apuntar un asistente de IA a un proyecto real de Unreal, te has encontrado 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 reexplicando lo que ya existe cada vez que abres una conversación nueva.

Este proyecto se construye alrededor de una idea: el modelo nunca debería recibir un volcado crudo del motor. Cada salto entre el Editor de Unreal y Claude compacta los datos: lecturas por niveles, ediciones basadas en diferencias, y un índice persistente que se construye una vez y se actualiza incrementalmente en lugar de reescanearse 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 sobre 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 o ejecutarlo.
• mcp-server es un servidor MCP en Node/TypeScript que traduce llamadas de herramientas MCP en solicitudes al puente, y es responsable de mantener cada respuesta económica: nombres de campos compactos, tamaños de resultados limitados, y sin re-serializar datos verbosos del motor tal cual.

Consulta ARCHITECTURE.md para el diseño completo.

Lo que puede hacer

101 herramientas, agrupadas por la tarea en lugar de por la API que llaman. Cada una se ejercita contra un proyecto real de ~1,000 Blueprints, no contra un fixture.

Entender un proyecto que no escribiste get_project_overview, search_project, find_references, map_system, explain_graph, list_blueprints, read_blueprint_summary, read_node_detail, describe_class, find_source, trace_variable, trace_function_calls, list_actors, read_class_defaults, undo_history. Pide "la cuenta atrás" y obtén el sistema completo: los Blueprints, las funciones, qué llama a qué, ordenados para lectura, en lugar de una lista de coincidencias de texto.

Encontrar errores, en lenguaje sencillo audit_project, review_blueprint, project_health, find_orphans, check_data_tables, read_runtime_errors, doctor. La auditoría pone precio a cada hallazgo, así que lo que aparece primero es lo que realmente te cuesta: un Parent: BeginPlay faltante, una variable replicada cuyo OnRep_ está vacío, una fila de Data Table que apunta a un asset eliminado, un grafo de eventos al que nada llega.

Construir funciones y demostrar que funcionan plan_feature, scaffold_blueprint, scaffold_widget, build_graph, add_node, connect_pins, add_event_handler, create_function, add_variable, set_variable_replication, auto_layout_graph, cleanup_blueprint, compile_blueprint, verify_feature. Los grafos salen ordenados y comentados, porque la salida que compila y la salida que alguien está contento de heredar son cosas diferentes.

Sea lo que sea de lo que esté hecho el trabajo Blueprints, C++ (find_source, compile_cpp, hot_reload_cpp), Data Tables, Data Assets, structs, enums, materiales e instancias, widgets UMG, asignaciones de entrada, niveles y actores, Animation Blueprints, Behavior Trees, Niagara. El soporte de lectura es deliberadamente más amplio que el de escritura, y el README dice cuál es cuál para cada uno.

Verlo ejecutarse de verdad start_pie, watch_runtime, pie_status, screenshot, run_console_command, stop_pie. Cada otra lectura aquí dice lo que un Blueprint afirma que hace. Estas dicen lo que hizo — incluyendo la única clase de error que una sola persona no puede reproducir sola:

Authority: 0 -> 490  changed=true
Client0:   0 -> 0    changed=false      <- the variable is not replicated

Añadido en el último día

115 commits. Las partes que vale la pena conocer:

• watch_runtime - observar un juego en ejecución. Muestrea variables en actores vivos durante el juego, en cada mundo PIE, etiquetadas por rol de red. Probado plantando un error de replicación en un proyecto real, observando solo la copia del servidor moverse, arreglándolo, y observando ambas moverse.
• hot_reload_cpp - el Ctrl+Alt+F11 que pulsa un humano. Hasta ahora, un modelo podía encontrar un error nativo, escribir la corrección y demostrar que compilaba — y el cambio quedaba en disco, porque el editor en ejecución mantiene la DLL. Aplicarlo significaba que tú cerraras el editor. Ahora es una sola llamada.
• run_console_command - la tecla de tilde. ce StartWave para disparar un evento que nada llama todavía, Ke * ResetHealth para llamar a una función en cada instancia, stat unit, slomo, cvars, trucos. Una definición en lugar de cuarenta, y reporta recognised: false para un error tipográfico en lugar de dejar que un comando mal escrito parezca uno que funcionó sin hacer nada.
• Las lecturas se abarataron de nuevo, medido. Contra el mismo grafo de 809 nodos: explain_graph 3,671 -> 2,329, get_project_overview 1,698 -> 829, y find_references y list_blueprints también compactados. Todo el bucle de encontrar-plantar-arreglar-probar es 9 llamadas y ~1,544 tokens, que npm run trial:diagnose ejecuta contra un editor en vivo en lugar de afirmar. Dos compactaciones más se midieron y se revirtieron — una ahorró 38 tokens y rompió cómo identificas naturalmente un actor.
• Detección de grafos muertos. Un punto fijo de vivacidad sobre todo el proyecto, sesgado hacia llamar cosas vivas: 52 de 511 grafos a los que nada llega, en el proyecto contra el que se validó. map_system y plan_feature ahora dicen explícitamente que un sistema que coincide con tu búsqueda puede ser el reemplazado, porque extender algo que nada llama produce una función que no puede ejecutarse.
• Nuevas lecturas: Animation Blueprints, Behavior Trees, Niagara, Data Assets. "Los enemigos no siguen" y "el efecto no se reproduce" son frases reales que la gente dice, y ninguna de ellas tenía nada sobre lo que aterrizar.
• Una clase de fallo nombrada y cazada. Una comprobación que reporta "no encontré problemas" y "no pude mirar" con la misma palabra. Cuatro instancias arregladas — el doctor que afirma un todo claro en un plugin que tenía dos comandos faltantes, find_orphans diciendo "limpio" cuando el nombre de clase no coincidía con nada, check_data_tables diciendo "limpio" cuando una columna estaba vacía en cada fila, y un preset que no tenía la única herramienta con la que su propio trabajo comienza.
• Las pruebas fueron sometidas a mutación. 444 pruebas, todas con aserciones — pero tener aserciones no es poder fallar. Doce mutaciones deliberadas; once atrapadas, una no. Esa llevó a un defecto real: un nombre de comprobación que se desvía o nunca se valoró puntúa silenciosamente 1 y se hunde bajo cada hallazgo cosmético.
• Una función construida y luego eliminada. Un nodo SpawnActor que las propias instrucciones de la herramienta habían reclamado durante meses. Estrelló el editor cuatro veces; todo se revirtió y el README ahora dice claramente que no se puede construir de esta manera. Una afirmación que no es verdad es peor que una función faltante.

Qué hace diferente a este

Ya hay 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, opt-in). Vale la pena ser directo sobre dónde este proyecto realmente difiere, en lugar de solo afirmar "mejor":

• Construido alrededor de la lectura, no solo de la escritura. La mayoría de los proyectos existentes son fuertes en crear y manipular Blueprints desde un prompt, pero no abordan lo que sucede cuando el modelo necesita entender un proyecto grande y ya construido primero. La lectura es la ciudadana de primera clase aquí: 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 assets una vez, lo guarda en caché en disco, y lo actualiza desde los delegados de AssetRegistry mientras editas, en lugar de reescanear el proyecto en cada consulta. find_references responde "qué usa realmente este Blueprint" sin que el modelo tenga que enumerar el proyecto mismo.

• Lecturas que caben en una ventana de contexto. Leer un grafo de Blueprint real — 807 nodos — solía devolver 126,477 tokens, 63% de una ventana de 200k en una sola llamada, de un proyecto cuya premisa completa es que el modelo nunca ve un volcado crudo del motor. Ahora es 3,110, con el grafo completo a un parámetro de distancia y un filtro match que responde una pregunta específica por una fracción de eso. Cada lectura se mide contra un proyecto real por npm run measure:reads, que encuentra el peor grafo mismo y falla la compilación si alguna lectura crece más allá de su techo.

• Una superficie de herramientas que cuesta 2.4k tokens en lugar de 34.8k. Las definiciones de herramientas se pagan en cada solicitud, antes de que tu mensaje se lea. El perfil search levanta cuatro herramientas y apaga las otras 97 — y porque están apagadas en lugar de ocultas detrás de un despachador genérico, unreal_enable_tools devuelve sus esquemas reales, completamente tipados. Una llamada extra al inicio de una sesión, nada sacrificado, y 32k tokens por turno ahorrados para el resto. Los números son medidos por npm run check:profiles, que falla la compilación si un perfil crece más allá de su presupuesto.

• Los grafos se leen y escriben como código. explain_graph con format: "dsl" devuelve un grafo como expresiones S — if/else reales, los argumentos literales de cada llamada, continuaciones nombradas para casts y nodos latentes — y build_graph toma el mismo texto de vuelta a través de su parámetro dsl. Cambiar un Blueprint se convierte en "léelo, edita dos líneas, envíalo de vuelta" en lugar de averiguar qué IDs de nodos recablear. Un grafo de ramificación de cinco nodos es 2,045 caracteres como estructura de nodo-y-pin y 302 como DSL:

  (event EventBeginPlay
    (bind v1 (cast BP_Door :Object (GetOwner))
      (:then
        (if bIsLocked
          (call PrintString :InString "locked" :Duration 2.0)
          (else
            (set bIsLocked true))))
      (:CastFailed
        (call PrintString :InString "not a door"))))
  

  La forma se toma del propio blueprint_dsl.py de Epic en el plugin de primera parte 5.8 — consulta docs/EPIC_58_TEARDOWN.md — pero el vocabulario es de este servidor, así que el texto viaja de ida y vuelta a través de nuestro propio escritor en lugar de su registro de herramientas.

• El servidor le dice al modelo cómo trabajar antes de que empiece. El campo instructions de MCP lleva el orden de llamadas y las cadenas exactas que ningún modelo puede recordar de manera fiable — el pin objetivo es self, las salidas de Sequence son then_0/then_1 — así que el modelo llega sabiéndolas en lugar de gastar llamadas fallidas descubriéndolas. unreal_guide luego le permite buscar cualquier otra cosa a mitad de tarea, una sección a la vez.

• Puede ver el juego ejecutarse, no solo leer los archivos. watch_runtime muestrea variables en actores vivos durante el juego, en cada mundo PIE, etiquetadas por rol de red. Los errores de replicación son la única clase de defecto que una sola persona no puede reproducir sola — Authority: 0 -> 490, Client0: 0 -> 0 es ese error observado en lugar de argumentado. Ningún otro proyecto en el estudio lee estado de ejecución en absoluto.

• Puede terminar un cambio en C++, no solo comprobarlo. compile_cpp demuestra que una edición compila; hot_reload_cpp lo parchea en el editor que ya está abierto, que es el Ctrl+Alt+F11 que pulsa un humano. Sin él, cada corrección nativa termina con un humano cerrando el editor.

• Los hallazgos tienen precio, así que el importante va primero. La auditoría puntúa cada hallazgo por lo que realmente te cuesta, y cada nombre de comprobación está protegido por una prueba — un nombre sin precio puntuaba silenciosamente 1 y se hundía bajo cada resultado cosmético, lo que se encontró mediante pruebas de mutación del conjunto en lugar de leyéndolo.

• Los veredictos distinguen "nada está mal" de "no pude mirar". Solían compartir una palabra, en cuatro lugares. Una herramienta que dice clean cuando no pudo comprobar es peor que una que no dice nada.

• Apunta tanto a 5.6 como a 5.8 desde un solo código base, donde varios proyectos existentes están fijados a una sola versión del motor. Los modelos locales pequeños siguen siendo compatibles y se siguen midiendo: el perfil minimal existe porque un 14B en una tarjeta de 12 GB carga con contexto de 8k y falla con 16k, pero ahora son una opción explícita en lugar de lo que la ruta de instalación le entrega silenciosamente a todos. También hay un hook opcional de modelo local para la indexación (UNREAL_MCP_LOCAL_LLM_URL), que genera resúmenes de búsqueda fuera de tu presupuesto de contexto. Totalmente opcional; el índice funciona sin él.

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

También hay un documento complementario que parte desde el otro extremo: docs/COMPLAINTS_SOLVED.md recopila las quejas que la gente realmente presenta sobre los servidores MCP de Unreal, cada una con su enlace de origen, y declara claramente si este proyecto la resuelve, la resuelve parcialmente o no la resuelve. Las filas abiertas se dejan abiertas a propósito.

Estado

Esto se está construyendo y verificando en público, hito por hito. El documento de estado de cada hito se escribe con honestidad, incluyendo qué está compilado/probado frente a qué sigue sin verificar:

• Hito 1: introspección de Blueprint 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 gráficos 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 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 cambios entre las dos versiones del motor.
• Hito 5: catálogo de verdad fundamental de nodos/funciones: unreal_find_node y unreal_get_node_signature, leyendo la superficie real invocable desde Blueprint del motor en ejecución mediante reflexión (12,402 funciones en 5.6, 15,775 en 5.8, construido en ~0.1s). 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 cuatro 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 confirmación de que el índice de proyecto incremental realmente se mantiene 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 de anulación ya presente. En 5.6 fue el .uplugin fijando rígidamente EngineVersion a 5.8.0: todas las comprobaciones de compilación pasaron porque UnrealBuildTool ignora ese campo, pero el cargador de plugins en tiempo de ejecución lo respeta, así que el editor se detuvo en un diálogo modal de incompatibilidad y el puente nunca arrancó.

Desde entonces, todo eso también se ha ejercitado en vivo: remove_node y VariableGet están cubiertos por las suites de id 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 gráfico condicional real solo a través del puente. Los ids de nodo son GUIDs persistentes, y cada escritura se puede deshacer con Ctrl+Z bajo una transacción nombrada "MCP:". 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 nodeType en lugar de descubrirse a través de unreal_find_node.

Inicio rápido (Instalación en 4 pasos)

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

1. Instalar el plugin de Unreal

Copia la carpeta del plugin UnrealMCPBridge en el 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.

Hay versiones precompiladas del plugin en la página de lanzamientos, y son más antiguas que este servidor. El puente ha ganado más de veinte comandos desde la última versión, y el número de protocolo no cambió, así que un plugin antiguo parece saludable y luego falla en la primera herramienta que necesita un comando que no tiene. --doctor ahora sondea específicamente esos comandos y lo dice. Compilar desde este checkout es la ruta confiable.

2. Construir el servidor MCP

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

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

3. Comprobar que funciona antes de conectar nada

Con el editor abierto, ejecuta:

node mcp-server/dist/index.js --doctor

Informa si el plugin es alcanzable, si su protocolo coincide con el servidor, si el índice del proyecto está construido o aún escaneando, si el catálogo de nodos del motor es legible y si una sesión PIE está en el camino. Cada comprobación fallida viene con el remedio, así que nunca tienes que adivinar cuál de seis cosas está mal. El código de salida 1 significa que no se pudo alcanzar el editor.

4. Registrar el servidor

No escribas la configuración a mano. Ejecuta esto desde el directorio de tu proyecto y escribirá los archivos:

node mcp-server/dist/index.js --install-config

Eso escribe todos los clientes de ámbito de proyecto a la vez — .mcp.json (Claude Code), .cursor/mcp.json, .vscode/mcp.json, .gemini/settings.json, .codex/config.toml — creando directorios según sea necesario. Si un archivo ya existe, solo se toca la entrada unreal; los servidores MCP que ya tenías se conservan, y un archivo que no sea JSON válido se rechaza en lugar de sobrescribirse.

node mcp-server/dist/index.js --install-config --client cursor          # just one client
node mcp-server/dist/index.js --install-config --client claude-desktop  # global, per-user config
node mcp-server/dist/index.js --install-config --dir /path/to/project   # somewhere other than cwd

Claude Desktop no es parte del barrido y debe nombrarse explícitamente, porque su configuración es global y se comparte con todos los demás proyectos de la máquina. Las ubicaciones de archivos y las claves raíz siguen el propio ModelContextProtocol.GenerateClientConfig de Epic en UE 5.8, así que son las que se les dirá a todos los desarrolladores de Unreal que esperen.

--print-config aún emite el JSON sin escribir nada, si prefieres pegarlo:

node mcp-server/dist/index.js --print-config                      # Claude Desktop
node mcp-server/dist/index.js --print-config --client cursor      # Cursor
node mcp-server/dist/index.js --print-config --client claude-code # Claude Code

Emite el JSON exacto para esta máquina, con rutas absolutas ya resueltas, y te dice en qué archivo va.

Eso existe porque la configuración del cliente es su propia categoría de fallos y todos son autoinfligidos: una coma faltante rompe todo el archivo, una ruta relativa no se resuelve silenciosamente, y en Windows un node desnudo puede no estar en el PATH que usa el cliente. Cada uno de esos produce el mismo síntoma: el servidor nunca arranca, sin explicación. La configuración impresa usa la ruta absoluta del Node que ejecutó el comando, así que no puede ser la incorrecta.

Luego cierra y reabre completamente el cliente. Cerrar la ventana no es suficiente, y es la razón más común por la que una configuración correcta parece no funcionar.

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

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

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

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

Qué cubre CI, y qué no

Estado: el flujo de trabajo está confirmado pero nunca se ha ejecutado. GitHub se negó a iniciarlo — "el trabajo no se inició porque tu cuenta está bloqueada debido a un problema de facturación" — así que no se muestra ninguna insignia aquí. Una insignia que diga "fallando" por una razón de facturación diría algo falso sobre el código. El flujo de trabajo es estructuralmente válido y toda la suite está verificada para pasar localmente sin editor en ejecución, que es lo mismo que hace en un runner; eso es una afirmación sobre ejecuciones locales, no un resultado de CI.

La insignia anterior cubre las partes que no necesitan instalación de Unreal, se ejecutan en una máquina Linux limpia sin nada preinstalado: compilación, verificación de tipos, paridad herramienta/puente, guardas de documentación, presupuestos de tokens de perfil, conformidad estricta del protocolo del cliente y las pruebas unitarias — en el Node más antiguo que promete el README y en el actual. También verifica que --doctor y --print-config se comporten correctamente sin editor en ejecución, ya que es exactamente cuando alguien recurre a ellos.

No ejecuta verificación en vivo ni el benchmark de modelo local. Esos necesitan un editor en ejecución, y uno necesita una GPU. Sus resultados viven en docs/LIVE_VERIFICATION.md y docs/LOCAL_MODEL_BENCHMARK.md, y se ejecutan a mano contra ambas versiones del motor. Reclamarlos en CI haría que la insignia significara menos de lo que significa.

El plugin C++ tampoco se compila en CI, porque Epic no distribuye un motor que se pueda obtener allí. npm run build:engines lo compila contra cada motor configurado localmente e informa éxito solo si cada uno realmente compiló.

Contribuciones

Las issues y los PRs son bienvenidos. 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.