# Referencia de la CLI — Unreal Engine · AI Game Developer Wiki

Referencia completa de unreal-mcp-cli: instala el plugin Unreal MCP, inicia sesión, configura agentes de IA, abre el editor y ejecuta Python.

Esta página se tradujo automáticamente del inglés. [Lee el original en inglés](https://ai-game.dev/docs/wiki/unreal/cli).

`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`.

```bash
npm install -g unreal-mcp-cli
unreal-mcp-cli --version
```

O ejecuta un solo comando sin instalarlo:

```bash
npx unreal-mcp-cli@latest status
```

Ejecuta `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).

```bash
unreal-mcp-cli create-project ./MyGame --engine 5.7
```

### install-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](https://ai-game.dev/es/docs/wiki/unreal/extensions), 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`.

```bash
unreal-mcp-cli install-extension com.ivanmurzak.unreal-ai-pcg ./MyGame --build
```

### bootstrap-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](https://ai-game.dev/es/docs/wiki/unreal/connecting-ai-clients#setup-mcp) 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.

```bash
unreal-mcp-cli exec "unreal.SystemLibrary.get_engine_version()" -p ./MyGame
```

Flags: `-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:

```bash
unreal-mcp-cli run-tool rql-query -p ./MyGame --input '{"query":"actors | select Label"}'
unreal-mcp-cli run-system-tool ping -p ./MyGame
```

Flags: `-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](https://ai-game.dev/es/docs/wiki/app).

---

Source (HTML): https://ai-game.dev/es/docs/wiki/unreal/cli

Machine-translated (es) from the English page: https://ai-game.dev/docs/wiki/unreal/cli