Instalación

Esta página muestra cómo instalar Unreal MCP, el plugin de AI Game Developer para Unreal Engine, en un proyecto. Elige una ruta de instalación, sigue sus pasos y luego continúa con Primeros pasos.

Requisitos#

El plugin no fija una versión exacta del motor en su descriptor, así que el mismo plugin se carga en versiones más recientes del motor.

Nota: Un proyecto solo de Blueprint necesita un módulo de C++ antes de poder compilar plugins. En el Unreal Editor, añade cualquier clase de C++ (Tools, New C++ Class) para convertirlo en un proyecto de C++, o crea un proyecto de C++ nuevo con unreal-mcp-cli create-project.

Opción 1: la app de escritorio AI Game Dev#

La app de escritorio es la ruta más sencilla. Incluye la lógica de instalación, así que no necesitas Node.js, npm ni una terminal.

1. Instala AI Game Dev desde la página de descarga. La guía de instalación de la app explica el proceso.
2. Inicia sesión con tu cuenta de ai-game.dev.
3. Elige Open folder… y selecciona la carpeta de tu proyecto de Unreal (la carpeta que contiene el archivo .uproject). La app lo detecta como un proyecto de Unreal. O usa Create new project para crear uno nuevo; entonces el plugin se instala automáticamente.
4. Haz clic en Install Package en la barra lateral. La app instala la versión más reciente publicada de Unreal MCP y verifica la descarga primero. Si el plugin instalado ya es más reciente, la app lo conserva.
5. Haz clic en Open Editor para abrir el Unreal Editor con tu sesión iniciada, de modo que el plugin se conecte a través de ai-game.dev sin necesidad de un token manual.

En la CLI de la app, las mismas acciones son los comandos /install-plugin y /open. La app también puede instalar las extensiones opcionales. Los detalles están en Proyectos y motores.

Opción 2: unreal-mcp-cli#

unreal-mcp-cli se publica en npm y funciona en Windows, macOS y Linux. No necesita clonar el repositorio ni un paso de compilación propio.

Instala la CLI globalmente:

npm install -g unreal-mcp-cli

O ejecuta cualquier comando una vez sin instalarla:

npx unreal-mcp-cli@latest status

Luego instala el plugin, inicia sesión y abre el editor:

# 1. Install the UnrealMCP plugin into <project>/Plugins/UnrealMCP
unreal-mcp-cli install-plugin ./YourProject

# 2. Sign in to ai-game.dev once per machine (device-code flow in your browser)
unreal-mcp-cli login

# 3. Open the Unreal Editor for the project
unreal-mcp-cli open ./YourProject

Qué hacen estos comandos:

• install-plugin descarga el código fuente del plugin que coincide con la versión de la CLI (unreal-mcp-plugin-source-<version>.zip de la release de GitHub) y comprueba su firma antes de extraerlo. Una descarga manipulada o sin firmar se rechaza. El bridge para tu plataforma viene dentro de ese paquete.
• login guarda tu credencial en el almacén de toda la máquina (~/.ai-game-dev/credentials.json), compartido con la app y las demás CLI de motores.
• open localiza el motor correcto a partir del EngineAssociation del proyecto, compila primero los módulos nativos del editor cuando es necesario, y descarta los avisos de inicio conocidos de Unreal (como "Missing Modules") si aún aparecen.

Consejo: Cierra el Unreal Editor antes de instalar o actualizar el plugin. Unreal no puede reemplazar un plugin que ha cargado un editor en ejecución.

Opción 3: instalación manual desde el código fuente#

La instalación manual está pensada para colaboradores y para el desarrollo del plugin.

1. Copia la carpeta UnrealMCP/ del repositorio Unreal-MCP en <YourProject>/Plugins/UnrealMCP/.
2. Una copia de trabajo del código fuente no incluye un bridge empaquetado. Compila uno con unreal-mcp-cli bootstrap-local ./YourProject (necesita el .NET 9 SDK), o apunta UNREAL_MCP_BRIDGE_PATH a un bridge que hayas compilado.
3. Abre el proyecto. Unreal compila los módulos del plugin en el primer inicio.

Para desarrollo en vivo, unreal-mcp-cli install-plugin --junction enlaza la carpeta del plugin en lugar de copiarla (Windows).

Fab / Epic Marketplace#

Está prevista una ficha en Fab, pero aún no está disponible. Hasta que se publique no hay nada que instalar desde Fab; usa la app o la CLI.

Comprobar la instalación#

Cuando el editor se inicia, el Output Log muestra:

[Unreal-MCP] plugin loaded

También puedes ejecutar unreal-mcp-cli status --path ./YourProject para ver el estado del paquete, el proyecto, el plugin y la conexión.

El plugin aparece entonces en el menú Tools del editor como AI Game Developer. Continúa con Primeros pasos.

Actualizar el plugin#

• App: la barra lateral muestra Update Package cuando existe una versión más reciente del plugin.
• CLI: ejecuta unreal-mcp-cli update ./YourProject. Cuando cambia la versión, elimina la carpeta Intermediate/ del plugin instalado y sus Binaries/ de C++ compilados para que Unreal haga una recompilación limpia, y conserva el bridge incluido. Añade --force para reinstalar la misma versión, o --no-clean para conservar la caché de compilación.
• Copia manual: cierra el editor, elimina Plugins/UnrealMCP/Intermediate/ y los Binaries/ de C++ (conserva Binaries/ThirdParty/) y vuelve a abrir el proyecto.

Una caché de compilación obsoleta es el motivo más habitual de que una actualización parezca no tener efecto. Consulta Solución de problemas.

Eliminar el plugin#

unreal-mcp-cli remove-plugin ./YourProject

O elimina <YourProject>/Plugins/UnrealMCP/ con el editor cerrado.

Mantener el plugin fuera de los juegos empaquetados#

Si usas Unreal MCP solo para la ayuda de IA en el editor, exclúyelo de las compilaciones empaquetadas en la entrada de plugin del .uproject de tu proyecto:

{
  "Name": "UnrealMCP",
  "Enabled": true,
  "TargetDenyList": ["Game", "Client", "Server"]
}

Así, el plugin sigue activo en el editor, pero nada de él, incluido el bridge, se compila ni se incluye en un juego empaquetado. No añadas ningún módulo UnrealMcp* a las dependencias del Build.cs de tu módulo de juego: una dependencia directa anula la lista de denegación. Para usar herramientas de IA dentro de un juego en ejecución, consulta herramientas en el juego.