UnrealMCP — MCP nativo para Unreal Engine 5.7

Inglés | 简体中文

UnrealMCP es un plugin de código autocontenido para el editor de Unreal Engine 5.7. Permite que Codex y otros clientes MCP locales inspeccionen y controlen un Unreal Editor abierto, exponiendo exactamente una herramienta MCP: unreal.

El plugin incluido no requiere Node.js, npm, un paquete de Python ni un servicio de puerta de enlace instalado por separado. Contiene ambos componentes de ejecución:

• Binaries/Win64/UnrealMCPGateway.exe — servidor MCP stdio nativo en C++ lanzado por el cliente MCP.

• Binaries/Win64/UnrealEditor-UnrealMCP.dll — módulo del editor que posee el worker de bucle de retorno y envía el trabajo de Unreal al hilo del juego.

Destacados

• Superficie de una sola herramienta: descubrimiento, comprobaciones de salud, ejecución y control asíncrono de tareas conviven tras unreal.

• Autocontenido: el plugin distribuible incluye el gateway stdio nativo y el worker de Unreal Editor.

• Compatibilidad con agentes: los lotes ordenados de Python/consola proporcionan una vía flexible a las API reflectadas de UE y a sistemas específicos del proyecto como UnLua.

• Seguro para el hilo del juego: las operaciones UObject y del editor se envían al hilo de juego de Unreal.

• Empaquetado orientado a Fab: la automatización de lanzamientos produce un ZIP limpio de un solo plugin, sin runtime externo.

flowchart LR
    C["Codex / MCP client"] -->|"stdio JSON-RPC"| G["Native gateway EXE"]
    G -->|"127.0.0.1 HTTP + optional bearer token"| P["UnrealMCP Editor plugin"]
    P -->|"Game Thread"| U["UE Python / console / UObject APIs"]

Estado y compatibilidad

El catálogo de capacidades cubre todos los grupos de plugins habilitados por el agregado oficial AllToolsets de UE 5.8 mediante los mecanismos de Python/reflexión y consola de UE 5.7. Un subsistema que solo existe en UE 5.8 no puede crearse en UE 5.7 estándar; los flujos de trabajo equivalentes funcionan cuando el subsistema 5.7 requerido o el plugin opcional está disponible. Consulta la cobertura de capacidades.

Tabla de contenidos

• Inicio rápido

• Instalación

• Conectar Codex

• Verificar la primera conexión

• La API de una sola herramienta

• Modelo de capacidades

• Compilar desde el código fuente

• Pruebas

• Solución de problemas

• Seguridad y límites operativos

• Mapa del repositorio

• Notas de distribución

Inicio rápido

1. Extrae el plugin de modo que el descriptor se encuentre en <Project>/Plugins/UnrealMCP/UnrealMCP.uplugin sin ningún directorio anidado adicional.

2. Habilita Minimal MCP for Unreal Editor y Python Editor Script Plugin, y reinicia Unreal Editor.

3. Guarda la configuración siguiente en ~/.codex/config.toml a nivel de usuario o en .codex/config.toml dentro de un proyecto de confianza. Sustituye el comando por la ruta absoluta del gateway.

4. Reinicia Codex, confirma que unreal está conectado con /mcp, y pide al agente que llame a la acción health.

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

Un resultado correcto incluye ok: true, la versión real del motor, is_game_thread: true y python_loaded: true. Unreal Editor debe permanecer abierto con el proyecto de destino cargado.

Instalación

Instalación del proyecto

Cierra Unreal Editor antes de copiar o sustituir binarios. Extrae o copia el directorio UnrealMCP empaquetado a:

<Project>/Plugins/UnrealMCP

El descriptor debe quedar en:

<Project>/Plugins/UnrealMCP/UnrealMCP.uplugin

Abre el proyecto, habilita Minimal MCP for Unreal Editor y Python Editor Script Plugin en Edit → Plugins y reinicia el editor.

Instalación en el motor

Para que el plugin esté disponible para varios proyectos que utilicen la misma compilación del motor, instálalo en:

C:/Program Files/Epic Games/UE_5.7/Engine/Plugins/Marketplace/UnrealMCP

Puede que se requieran permisos de administrador. Una instalación local al proyecto suele ser más fácil de versionar con el proyecto y tiene prioridad para el desarrollo.

Conectar Codex

Codex desktop, la CLI de Codex y la extensión del IDE comparten la configuración de MCP. Los servidores stdio locales se inician desde el command configurado. La configuración puede estar globalmente en ~/.codex/config.toml, o en .codex/config.toml dentro de un proyecto de confianza. Consulta la documentación oficial de Codex MCP.

Usa barras normales en una ruta TOML de Windows:

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

También puedes añadir el servidor en Codex desktop en Settings → MCP servers → Add → STDIO. Después de guardar la configuración, reinicia Codex y usa /mcp para confirmar que el servidor está conectado.

El cliente MCP inicia solo el gateway nativo. No lanza Unreal Editor. Abre el proyecto de destino en Unreal Editor antes de realizar una llamada de herramienta.

Puerto y autenticación

El worker se vincula únicamente a 127.0.0.1. El editor y el gateway leen estas variables de entorno de forma independiente:

Para la autenticación, establece el mismo token antes de lanzar Unreal Editor y Codex. No hagas commit del token:

$env:UE_MCP_WORKER_TOKEN = '<a-long-random-token>'
$env:UE_MCP_WORKER_PORT = '18777'
& 'C:\Program Files\Epic Games\UE_5.7\Engine\Binaries\Win64\UnrealEditor.exe' 'C:\path\Project.uproject'

Si Codex no se lanza desde esa shell, proporciona los mismos valores a la configuración de su servidor MCP:

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

[mcp_servers.unreal.env]
UE_MCP_WORKER_PORT = "18777"
UE_MCP_WORKER_TOKEN = "replace-with-the-same-token-used-by-the-editor"
UE_MCP_TIMEOUT_MS = "30000"

Verificar la primera conexión

Pide al cliente MCP que llame a unreal con:

{
  "action": "health"
}

Una respuesta correcta tiene esta forma:

{
  "ok": true,
  "data": {
    "ok": true,
    "engine_version": "5.7.x-...",
    "is_game_thread": true,
    "python_loaded": true,
    "transport": "loopback-http"
  }
}

A continuación, verifica una lectura del motor:

{
  "action": "execute",
  "transaction": false,
  "commands": [
    {
      "kind": "python",
      "mode": "eval",
      "label": "engine-version",
      "code": "unreal.SystemLibrary.get_engine_version()"
    }
  ]
}

eval evalúa una expresión de Python y devuelve su valor. exec ejecuta sentencias o un script multilínea. El módulo unreal está disponible en el entorno de ejecución de Python del plugin.

La API de una sola herramienta

unreal utiliza un esquema discriminado por acciones para que el cliente MCP reciba solo una definición de herramienta, conservando a la vez el descubrimiento, la ejecución, las comprobaciones de salud y el control de tareas de larga duración.

Descubrir capacidades

Busca en el catálogo de capacidades independiente antes de elegir las API de UE:

{
  "action": "discover",
  "query": "create and compile a blueprint",
  "limit": 5
}

Usa domain para un dominio exacto como blueprint, asset, niagara, pcg, slate, umg o unlua. Llamar a discover sin consulta devuelve entradas del catálogo hasta el límite solicitado.

Ejecutar un lote ordenado

Un lote execute acepta hasta 100 comandos de Python o consola. Los comandos se ejecutan en orden en el hilo del juego.

{
  "action": "execute",
  "run": "sync",
  "transaction": true,
  "continue_on_error": false,
  "timeout_ms": 120000,
  "commands": [
    {
      "kind": "python",
      "mode": "exec",
      "label": "select-all-static-mesh-actors",
      "code": "subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)\nactors = subsystem.get_all_level_actors()\nsubsystem.set_selected_level_actors([a for a in actors if isinstance(a, unreal.StaticMeshActor)])"
    },
    {
      "kind": "console",
      "label": "show-fps",
      "command": "stat fps"
    }
  ]
}

• transaction tiene true como valor predeterminado y crea un registro de deshacer del editor cuando todo el lote tiene éxito.

• continue_on_error tiene false como valor predeterminado; cuando está habilitado, los comandos posteriores se ejecutan de todos modos y el resultado general sigue siendo fallido si algún comando falló.

• timeout_ms acepta de 100 a 3600000 milisegundos y sobrescribe UE_MCP_TIMEOUT_MS en esa llamada.

• Los resultados de Python y los registros de Python capturados, o la salida de consola, se devuelven por comando.

Usa transaction: false para consultas de solo lectura y API que no participan en transacciones de Unreal. Una transacción de Unreal es un registro de deshacer, no una reversión del sistema de archivos ni del control de versiones.

Ejecutar e inspeccionar trabajo asíncrono

Para un lote largo, envíalo de forma asíncrona:

{
  "action": "execute",
  "run": "async",
  "timeout_ms": 3600000,
  "commands": [
    {
      "kind": "console",
      "command": "Automation RunTests Project"
    }
  ]
}

La respuesta contiene un task_id. Consulta o lista las tareas con:

{ "action": "task", "command": "get", "task_id": "<uuid>" }

{ "action": "task", "command": "list" }

Marca una tarea como cancelada con:

{ "action": "task", "command": "cancel", "task_id": "<uuid>" }

El estado de la tarea se mantiene en el proceso del gateway y se pierde cuando Codex detiene ese proceso. La cancelación se realiza con el mejor esfuerzo: marca el seguimiento como cancelado, pero el trabajo ya enviado al hilo de juego de Unreal puede completarse igualmente y no se revierte.

Modelo de capacidades

El plugin evita deliberadamente cientos de herramientas wrapper estrechas. discover proporciona recetas y API preferidas; execute alcanza la superficie reflectada de Python de UE 5.7, los comandos de consola, los plugins opcionales del motor y las API específicas del proyecto como UnLua.

El catálogo cubre los 21 grupos de AllToolsets de UE 5.8, incluidos trabajo de editor/asset/Blueprint, IA y navegación, animación, automatización, configuración, conversaciones, Data Registry, Dataflow, Game Features, Gameplay Tags y GAS, Niagara, PCG, física, plugins, búsqueda semántica, Slate, StateTree, UMG y World Conditions.

La cobertura es de enrutamiento y mecanismo, no una afirmación de que las clases exclusivas de UE 5.8 existan en UE 5.7. Los flujos de trabajo opcionales requieren que su correspondiente plugin del motor o del proyecto esté habilitado. La justificación y las cinco pasadas de minimización están documentadas en minimización de herramientas.

Compilar desde el código fuente

Requisitos:

• Instalación de código fuente/compilación de Unreal Engine 5.7. Los scripts usan por defecto C:\Program Files\Epic Games\UE_5.7.

• Cadena de herramientas C++ de Visual Studio compatible con UE 5.7.

• PowerShell.

• Node.js 20+ solo para las pruebas opcionales del protocolo MCP; Node no es una dependencia de ejecución del producto.

Compila el gateway nativo en el lugar:

.\scripts\build-native-gateway.ps1

Compila un paquete completo del plugin en un directorio nuevo:

.\scripts\build-plugin.ps1 -OutputDirectory 'C:\Temp\UnrealMCP-Package'

Crea el ZIP de Fab de un solo nivel superior:

.\scripts\build-fab-package.ps1 -OutputFile '.\artifacts\UnrealMCP-0.2.0-UE5.7-Win64.zip'

El plugin empaquetado contiene el descriptor, el código fuente, la configuración, los recursos, la DLL y el EXE nativos, los avisos de licencia, los README en inglés y chino simplificado, y los documentos de diseño. El ZIP de Fab contiene exactamente un directorio UnrealMCP/ de nivel superior y excluye Intermediate, los archivos PDB, los paquetes de Node y el proyecto de prueba de desarrollo.

Cada versión del motor y plataforma necesita su propio paquete binario compilado y probado. El descriptor actual tiene como destino solo Win64.

Pruebas

Ejecuta las pruebas de metadatos y de integración MCP nativa moderna/heredada:

npm install
npm test

Ejecuta la ruta completa: gateway nativo stdio → worker de bucle de retorno → hilo del juego → Python de UE:

.\scripts\build-native-gateway.ps1
.\scripts\test-worker-e2e.ps1

La prueba de extremo a extremo lanza el UE57MCPTest.uproject incluido sin interfaz gráfica en un puerto aislado y lo cierra tras la verificación. Cierra las instancias de pruebas automatizadas no relacionadas si el puerto elegido está ocupado.

Solución de problemas

La puerta de enlace escribe mensajes de protocolo MCP solo en stdout y diagnósticos en stderr. Los errores de inicio del plugin, enlace, autorización y ejecución aparecen en el Unreal Output Log bajo LogUnrealMCP.

Límites de seguridad y operativos

execute permite intencionalmente comandos arbitrarios de Python y consola de Unreal. Trata el acceso a esta herramienta como equivalente a permitir que el agente opere el proyecto de editor abierto.

• El worker solo se vincula a loopback; no es un servicio de red remoto.

• La autenticación Bearer es opcional pero recomendada en máquinas compartidas.

• Los cuerpos de solicitud se limitan a 4 MiB y los lotes a 100 comandos.

• El acceso a UObject y al editor se ejecuta en el Game Thread.

• No coloques secretos en argumentos de herramientas, archivos de proyecto, registros o configuración de Codex confirmada.

• Usa control de versiones para operaciones destructivas de activos, configuración, plugin y sistema de archivos.

Mapa del repositorio

Notas de distribución

El ZIP generado está estructurado como un único plugin de código UE instalable adecuado para la revisión técnica de Fab. La publicación en Marketplace aún requiere metadatos de vendedor/listado y activos visuales como el icono del plugin y capturas de pantalla, además de un paquete probado para cada versión de motor y plataforma anunciada.

Los detalles de la licencia están en LICENSE, y los avisos de terceros en THIRD_PARTY_NOTICES.md. Notas de diseño adicionales: arquitectura, cobertura de capacidades y minimización de herramientas.

Si este proyecto te ha ayudado, por favor considera darle una estrella ⭐