Referencia de la CLI
Referencia completa de unreal-mcp-cli: instala el plugin Unreal MCP, inicia sesión, configura agentes de IA, abre el editor y ejecuta Python.
unreal-mcp-cli es la herramienta de línea de comandos de Unreal MCP. Instala y actualiza el plugin, inicia sesión en ai-game.dev, escribe configuraciones MCP para agentes de IA, lanza el Unreal Editor con los ajustes de conexión adecuados y llama a herramientas desde scripts y CI. Funciona en Windows, macOS y Linux. Esta página cubre la versión 0.26.2.
Instalar la CLI
Requiere Node.js ^20.19.0 o >=22.12.0.
npm install -g unreal-mcp-cli
unreal-mcp-cli --versionO ejecuta un solo comando sin instalarlo:
npx unreal-mcp-cli@latest statusEjecuta unreal-mcp-cli <command> --help para ver la ayuda integrada de cualquier comando. El flag global -v, --verbose imprime diagnósticos adicionales.
Nota: Los comandos que toman el proyecto como [path] lo aceptan como argumento posicional. Los comandos sin [path] lo toman con -p, --path <dir>. Ambos usan por defecto la carpeta actual. Pasar una ruta posicional a un comando con --path falla con "too many arguments".
Resumen de comandos
| Comando | Propósito |
|---|---|
create-project <path> | Genera un proyecto C++ mínimo de Unreal Engine |
install-plugin [path] | Instala el plugin UnrealMCP en <project>/Plugins |
update [path] | Actualiza el plugin instalado |
remove-plugin [path] | Elimina el plugin |
install-extension <id> [path] | Instala una extensión de Unreal MCP |
login | Inicia sesión en ai-game.dev (flujo de código de dispositivo) |
configure | Escribe los valores UNREAL_MCP_* en <project>/.env |
setup-mcp [agent] | Escribe una configuración MCP para un agente de IA |
setup-skills | Escribe una skill de Claude Code para el proyecto |
open [path] | Lanza el Unreal Editor con los ajustes de conexión |
close [path] | Cierra el editor que está ejecutando el proyecto |
exec [code] | Ejecuta Python en el editor |
status | Muestra el estado del paquete, el proyecto, el plugin y la conexión |
wait-for-ready | Espera hasta que el servidor MCP del proyecto responda |
run-tool <tool> | Llama a una herramienta MCP por HTTP |
run-system-tool <tool> | Llama a una herramienta del sistema por HTTP |
bootstrap-local [path] | Compila el puente desde el código fuente |
install-engine [version] | Detecta los motores instalados y enlaza con el launcher de Epic |
Comandos de configuración del proyecto
create-project
Genera un proyecto C++ mínimo. Opciones: --name <name> (nombre del proyecto y del módulo; letras, dígitos y guiones bajos, sin guiones), --engine <version> (la EngineAssociation, por ejemplo 5.7), --force (permite una carpeta no vacía).
unreal-mcp-cli create-project ./MyGame --engine 5.7install-plugin
Instala el plugin. Si no hay una fuente local, descarga del release de GitHub el código fuente del plugin que corresponde a la versión de la CLI y verifica primero su firma.
| Opción | Significado |
|---|---|
--version <v> | Release del plugin que se descarga (por defecto: la versión de la CLI) |
--plugin-source <dir> | Usa una carpeta de plugin local (offline, CI, desarrollo) |
--junction | Enlaza en lugar de copiar (Windows, para desarrollo de plugins) |
--with-server | También descarga el gamedev-mcp-server verificado con checksum |
--server-version <v>, --server-source <path-or-url> | Versión del servidor, o una fuente local o personalizada, para --with-server |
--enroll <code>, --enroll-stdin | Canjea un código de enrolamiento de agente en lugar de un inicio de sesión por navegador |
--base-url <url> | URL base de autenticación para --enroll |
-y, --yes | Confirma el cambio de la máquina a otra cuenta |
update
Vuelve a sincronizar el plugin instalado. Cuando cambia la versión, elimina los Intermediate/ y los Binaries/ de C++ obsoletos para que Unreal recompile limpiamente, conservando el puente incluido. Flags: --version <v>, --plugin-source <dir>, --force (reinstala la misma versión), --no-clean (conserva la caché de compilación).
remove-plugin
Elimina Plugins/UnrealMCP del proyecto. Sin opciones.
install-extension
Instala una extensión, la habilita a ella y a su plugin de motor en el .uproject. Flags: --version <x.y.z>, --source <dir>, --build (compila ahora), --engine-root <dir> (motor para --build), --force.
unreal-mcp-cli install-extension com.ivanmurzak.unreal-ai-pcg ./MyGame --buildbootstrap-local
Compila el puente desde el código fuente en <project>/Intermediate/UnrealMCP/ para checkouts de código fuente; requiere el SDK de .NET 9. Flags: --repo-root <dir>, --plan (solo imprime el plan de compilación).
install-engine
Lista los motores instalados o comprueba si hay una versión concreta. Nunca descarga un motor; si falta una versión, te da un enlace al Epic Games Launcher. Flags: --manifest <path> (LauncherInstalled.dat explícito), --install, --yes.
Comandos de inicio de sesión y de agentes de IA
login
Inicia sesión con el flujo OAuth de código de dispositivo y guarda la credencial en ~/.ai-game-dev/credentials.json, compartida por todas las herramientas de AI Game Dev de la máquina.
| Opción | Significado |
|---|---|
-p, --path <dir> | Guarda la credencial en el .env de ese proyecto en lugar de en el almacén de la máquina |
--tools-only | Crea una credencial solo para herramientas para runners de CI (la app no puede usarla) |
-y, --yes | Confirma el cambio de la máquina a otra cuenta |
--base-url <url> | URL base de autenticación (por defecto https://ai-game.dev) |
--timeout <ms> | Tiempo máximo total de sondeo |
configure
Escribe los valores UNREAL_MCP_* en <project>/.env y añade .env al gitignore. Flags: -p, --path, --mode <Cloud|Custom>, --host <url>, --cloud-url <url>, --token <token>, --auth <option>, --keep-connected, --tools <list>, --start-server, --transport <stdio|http>, --log-level <level>, --no-gitignore.
Con --agent <id>, en su lugar pide al gamedev-mcp-server gestionado que escriba una configuración de cliente fijada; los flags relacionados son --url, --server-version y --server-source.
setup-mcp
Escribe una entrada de configuración MCP para un agente. Consulta Conexión de clientes de IA para ver la lista de agentes.
| Opción | Significado |
|---|---|
-p, --path <dir> | Carpeta del proyecto |
--transport <t> | http (por defecto) o stdio (descarga el servidor local) |
--url <url> | URL del servidor explícita |
--token <token> | Token bearer explícito; tiene prioridad sobre la clave del proyecto |
--oauth | Cloud: configuración solo con URL, el agente inicia sesión por sí mismo |
--regenerate-key | Cloud: crea una nueva clave de proyecto y revoca la anterior |
--no-pin | URL /mcp simple en lugar de la /mcp/p/<pin> fijada al proyecto |
--dry-run | Imprime el fragmento sin escribirlo |
--list | Lista los agentes compatibles y las rutas de configuración |
setup-skills
Escribe .claude/skills/unreal-mcp/SKILL.md. Flags: -p, --path, --url, --token, --force (sobrescribe).
Comandos del editor
open
Lanza el Unreal Editor y pasa los ajustes de conexión como variables de entorno UNREAL_MCP_*. El motor proviene del EngineAssociation del proyecto; un motor compilado desde código fuente requiere --engine-root.
| Opción | Significado |
|---|---|
--connection-mode <mode> | Custom o Cloud; --host por sí solo implica Custom |
--host, --token, --auth, --tools, --transport | Establece la variable UNREAL_MCP_* correspondiente |
--keep-connected, --start-server | Establece la variable correspondiente a true |
--no-connect | No pasa ninguna variable UNREAL_MCP_* |
--headless | Inicia un editor sin ventana propiedad de la CLI y espera hasta que esté listo |
--idle <seconds>, --url <url> | Cierre por inactividad y URL del servidor para un editor propiedad de la CLI |
--engine-root <dir> | Carpeta del motor para compilaciones desde código fuente |
--no-build | Omite la compilación previa al lanzamiento de los módulos nativos |
--no-auto-dismiss-startup-dialogs | No toca los avisos de inicio de Unreal |
--startup-dismiss-timeout-ms, --startup-dismiss-poll-interval-ms | Ajusta el descarte de avisos (por defecto 12000 y 1000) |
--no-cache | Vuelve a descubrir la ruta del motor |
En Linux, el descarte de los avisos de inicio solo funciona en X11.
close
Cierra el editor que está ejecutando el proyecto. Con --owned-only solo cierra un editor iniciado por la CLI (mediante exec u open --headless), que guarda y se cierra; nunca se toca un editor que hayas abierto tú. --force mata un editor propiedad de la CLI que no se cierra a tiempo; --token sobrescribe el token bearer.
exec
Ejecuta Python en el editor mediante python-execute. Reutiliza un editor en ejecución o inicia uno headless que renderiza fuera de pantalla (para que las capturas de pantalla sigan funcionando) y se cierra tras un periodo sin llamadas a herramientas.
unreal-mcp-cli exec "unreal.SystemLibrary.get_engine_version()" -p ./MyGameFlags: -p, --path, -f, --file <file> (- para stdin), --include <path> (helpers de .ai-game-dev/snippets, repetible), --window, --idle <seconds> (por defecto 300, 0 = nunca), --ready-timeout <ms>, --timeout <ms>, --raw (imprime la respuesta JSON), --url, --token, --engine-root, --no-build. Los resultados se imprimen en stdout; print() y las líneas de log, en stderr.
Comandos de herramientas y de estado
status y wait-for-ready
status informa de la CLI, el proyecto, el plugin y la conexión, con una prueba de accesibilidad en vivo (--no-probe la omite). wait-for-ready bloquea hasta que el servidor responde a un ping (--timeout, por defecto 120000 ms; --interval, por defecto 2000 ms). Ambos aceptan -p, --path, --url y --token.
run-tool y run-system-tool
Llama a una herramienta mediante el servidor MCP local del proyecto:
unreal-mcp-cli run-tool rql-query -p ./MyGame --input '{"query":"actors | select Label"}'
unreal-mcp-cli run-system-tool ping -p ./MyGameFlags: -p, --path, --url, --token, --input <json>, --input-file <file> (- para stdin), --timeout <ms> (por defecto 60000).
La misma lógica está disponible como biblioteca tipada (import { openProject, runTool } from 'unreal-mcp-cli'), usada por la app de AI Game Dev.