# Referencia de unity-mcp-cli — Unity · AI Game Developer Wiki

Referencia de comandos de unity-mcp-cli: instala Unity MCP, inicia sesión, configura agentes de IA y ejecuta herramientas y C# desde la terminal.

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

`unity-mcp-cli` es la herramienta de línea de comandos para Unity MCP. Instala Unity y el plugin, inicia tu sesión en ai-game.dev, escribe configuraciones de agentes de IA, abre y cierra el Editor, y llama a herramientas MCP o ejecuta C# en el Editor desde una terminal o un script de CI. Esta página enumera todos los comandos y flags de la versión 1.6.2.

## Instalación

```bash
npm install -g unity-mcp-cli
```

O ejecuta cualquier comando sin instalarlo: `npx unity-mcp-cli <command>`. Requiere Node.js `^20.19.0` o `>=22.12.0` y funciona en Windows, macOS y Linux. Los comandos que gestionan editores usan la CLI de Unity Hub; si falta Unity Hub, la CLI lo instala.

Opciones globales, disponibles en todos los comandos:

| Opción | Descripción |
| --- | --- |
| `-v, --verbose` | Salida de diagnóstico detallada |
| `-V, --version` | Muestra la versión de la CLI |
| `--help` | Ayuda del comando |

En una terminal no interactiva (CI), la CLI desactiva automáticamente los spinners y los colores. La mayoría de los comandos que aceptan una ruta de proyecto la reciben como argumento posicional o como `--path`, y usan por defecto la carpeta actual.

## Una sesión típica

```bash
unity-mcp-cli install-plugin ./MyGame
unity-mcp-cli login
unity-mcp-cli setup-mcp claude-code ./MyGame
unity-mcp-cli open ./MyGame
unity-mcp-cli wait-for-ready ./MyGame
unity-mcp-cli run-tool tests-run ./MyGame --input '{"testMode":"EditMode"}'
unity-mcp-cli close ./MyGame
```

## Comandos de configuración del proyecto

### install-unity

Instala un Editor de Unity a través de Unity Hub. Sin argumentos, instala la última versión estable.

| Argumento / opción | Descripción |
| --- | --- |
| `[version]` | Versión del Editor, por ejemplo `6000.3.1f1` |
| `--path <path>` | Lee la versión requerida de un proyecto existente |

### create-project

Crea un nuevo proyecto de Unity con el Editor: `unity-mcp-cli create-project ./MyGame --unity 6000.3.1f1`.

| Argumento / opción | Descripción |
| --- | --- |
| `[path]` | Dónde crear el proyecto (obligatorio, o `--path`) |
| `--unity <version>` | Versión del Editor (por defecto: la más alta instalada) |

### install-plugin

Añade el registro con ámbito de OpenUPM y `com.ivanmurzak.unity.mcp` a `Packages/manifest.json`. Nunca degrada una versión instalada superior. La carpeta debe ser un proyecto de Unity.

| Opción | Descripción |
| --- | --- |
| `[path]` | Proyecto de Unity (por defecto: la carpeta actual) |
| `--plugin-version <version>` | Versión a instalar (por defecto: la última en OpenUPM) |
| `--with-server` | Descarga también el binario `gamedev-mcp-server` para esta máquina en la carpeta propia de la CLI |
| `--server-version <version>` | Versión del servidor para `--with-server` |
| `--server-source <path-or-url>` | Instala el servidor desde un zip local o una URL (offline o CI; omite la verificación de checksum) |
| `--enroll <code>` | Canjea un código de inscripción de equipo por una credencial del plugin vinculada a este proyecto |
| `--enroll-stdin` | Lee el código de inscripción desde stdin, manteniéndolo fuera del historial del shell |
| `--yes` | Confirma las preguntas, como un cambio de cuenta durante `--enroll` |

### install-extension

Instala una extensión oficial en `Packages/manifest.json`. Consulta [Extensions](https://ai-game.dev/es/docs/wiki/unity/extensions).

| Argumento / opción | Descripción |
| --- | --- |
| `[id]` | Nombre del catálogo (`Tilemap`) o id del paquete (`com.ivanmurzak.unity.mcp.tilemap`) |
| `[path]` | Proyecto de Unity (por defecto: la carpeta actual) |
| `--extension-version <version>` | Versión a instalar (por defecto: la última en OpenUPM) |
| `--list` | Lista las extensiones instalables y sale (no requiere proyecto ni red) |

### remove-plugin

Elimina `com.ivanmurzak.unity.mcp` de `Packages/manifest.json` y conserva los registros con ámbito. Acepta `[path]` (obligatorio, o `--path`).

### configure

Muestra u oculta herramientas, prompts y recursos en `UserSettings/AI-Game-Developer-Config.json`. Un elemento oculto se sigue ejecutando cuando se llama por su nombre.

| Opción | Descripción |
| --- | --- |
| `[path]` | Proyecto de Unity (obligatorio, o `--path`) |
| `--list` | Muestra la configuración actual y sale |
| `--enable-tools <names>`, `--disable-tools <names>` | Muestra u oculta herramientas concretas (separadas por comas) |
| `--enable-all-tools`, `--disable-all-tools` | Muestra u oculta todas las herramientas |
| `--enable-prompts <names>`, `--disable-prompts <names>` | Lo mismo para los prompts |
| `--enable-all-prompts`, `--disable-all-prompts` | Todos los prompts |
| `--enable-resources <names>`, `--disable-resources <names>` | Lo mismo para los recursos |
| `--enable-all-resources`, `--disable-all-resources` | Todos los recursos |
| `--agent <id>` | Escribe en su lugar una configuración de agente de IA mediante el configurador del servidor gestionado |
| `--url <url>` | URL del servidor que se pasa junto con `--agent` |

### bootstrap-local

Fija la configuración de un proyecto en modo Custom (local) con una URL de servidor y un token determinados. Idempotente.

| Opción | Descripción |
| --- | --- |
| `[path]` | Proyecto de Unity (por defecto: la carpeta actual) |
| `--url <url>` | URL del servidor MCP local (obligatorio) |
| `--token <token>` | Token bearer local (obligatorio) |
| `--dry-run` | Informa de lo que cambiaría sin escribir nada |

## Comandos de inicio de sesión y de agentes de IA

### login

Inicia sesión en ai-game.dev con el flujo de dispositivo OAuth del navegador y guarda la credencial en `~/.ai-game-dev/credentials.json`. El plugin del Editor y la aplicación de escritorio usan la misma credencial. Si ya has iniciado sesión, termina de inmediato.

| Opción | Descripción |
| --- | --- |
| `--project <path>` | Guarda la credencial en `<path>/.ai-game-dev/` en lugar del almacén de la máquina |
| `--force` | Vuelve a iniciar sesión aunque ya exista una credencial |
| `--tools-only` | Autoriza solo las herramientas del motor, para runners de CI; no se guarda ninguna credencial de agente |
| `--yes` | Confirma un cambio de cuenta sin preguntar |

### setup-mcp

Escribe la configuración MCP de un agente de IA, la misma salida que **Configure** en la ventana del Editor. De forma predeterminada, la URL está vinculada a este proyecto (`https://ai-game.dev/mcp/p/<pin>`) y, en las configuraciones HTTP de Cloud, incluye la clave de este proyecto cuando has iniciado sesión. Consulta [Conectar clientes de IA](https://ai-game.dev/es/docs/wiki/unity/connecting-ai-clients).

| Opción | Descripción |
| --- | --- |
| `[agent-id]` | Agente que se va a configurar, por ejemplo `claude-code`, `cursor`, `codex` |
| `[path]` | Proyecto de Unity (predeterminado: la carpeta actual) |
| `--transport <transport>` | `http` (predeterminado) o `stdio` |
| `--url <url>` | Sobrescribe la URL del servidor para `http` |
| `--token <token>` | Escribe este Personal Access Token en lugar de la clave del proyecto |
| `--oauth` | Escribe una configuración solo con URL; el agente inicia sesión con su propio OAuth |
| `--regenerate-key` | Genera una nueva clave de proyecto, reescribe las configuraciones y revoca la clave anterior |
| `--no-pin` | Usa el endpoint sin vincular `https://ai-game.dev/mcp` |
| `--list` | Muestra los ids de los agentes y las rutas de sus configuraciones |

### setup-skills

Genera los archivos de habilidades del agente mediante el Editor en ejecución. Unity debe estar abierto con el plugin conectado.

| Opción | Descripción |
| --- | --- |
| `[agent-id]` | Agente para el que se generan las habilidades |
| `[path]` | Proyecto de Unity (predeterminado: la carpeta actual) |
| `--url <url>`, `--token <token>` | Sobrescribe la URL del servidor y el token |
| `--timeout <ms>` | Tiempo de espera de la solicitud (predeterminado 60000) |
| `--list` | Muestra los agentes y si admiten habilidades |

## Comandos del Editor

### open

Abre el proyecto en el Editor de Unity y establece las variables de entorno de conexión del plugin a partir de las opciones indicadas. El editor se inicia de forma independiente.

| Opción | Descripción |
| --- | --- |
| `[path]` | Proyecto de Unity (predeterminado: la carpeta actual) |
| `--unity <version>` | Versión del Editor (predeterminado: la versión del proyecto y, después, la más alta instalada) |
| `--editor-path <path>` | Ejecutable del Editor explícito; omite la detección de Unity Hub |
| `--no-connect` | Abre sin variables de conexión MCP |
| `--url <url>` | URL del servidor (establece `UNITY_MCP_HOST`, el alias de `UNITY_MCP_CLOUD_URL`) |
| `--keep-connected` | Fuerza la conexión |
| `--token <token>` | Token del servidor local (establece `UNITY_MCP_TOKEN`) |
| `--auth <option>` | Modo de autorización (establece `UNITY_MCP_AUTH_OPTION`); esta versión acepta `none` o `required` |
| `--tools <names>` | Herramientas que se muestran, separadas por comas (establece `UNITY_MCP_TOOLS`) |
| `--transport <method>` | `streamableHttp` o `stdio` |
| `--start-server <value>` | `true` o `false` para el inicio automático del servidor local |
| `--headless` | Inicia sin ventana (`-batchmode`, con gráficos) y espera hasta que el servidor MCP responda |
| `--idle-timeout <seconds>` | Cierra tras este número de segundos sin llamadas a herramientas, guardando antes las escenas y los assets modificados |
| `--ready-timeout <ms>` | Con `--headless`, cuánto tiempo esperar (predeterminado 300000) |
| `--no-auto-dismiss-launch-errors` | No hace clic en **Ignore** en el diálogo de Unity «errores de compilación al iniciar» |
| `--launch-dismiss-timeout-ms <ms>` | Tiempo total para vigilar ese diálogo (predeterminado 30000) |
| `--launch-dismiss-poll-interval-ms <ms>` | Intervalo de sondeo del diálogo (predeterminado 1500) |

Para descartar el diálogo de errores de inicio se necesita el permiso de Accesibilidad para la terminal en macOS y `xdotool` en Linux X11 (Wayland no es compatible).

### close

Cierra el Editor del proyecto de forma ordenada: `unity-mcp-cli close ./MyGame --timeout 60 --force`. Cerrar un Editor que no está en ejecución se considera correcto.

| Opción | Descripción |
| --- | --- |
| `[path]` | Proyecto de Unity (predeterminado: la carpeta actual) |
| `--timeout <seconds>` | Espera a un cierre ordenado (predeterminado 30) |
| `--force` | Mata el Editor si no se ha cerrado para entonces |
| `--owned-only` | Cierra solo un Editor iniciado por la CLI (`exec`, `open --headless`) |

### wait-for-ready

Sondea hasta que el Editor y el servidor MCP aceptan llamadas a herramientas. Opciones: `[path]`, `--url`, `--token`, `--timeout <ms>` (predeterminado 120000) y `--interval <ms>` (predeterminado 3000).

### status

Muestra si Unity está en ejecución, si el servidor MCP local responde y si el servidor configurado (por ejemplo, la nube) es accesible. Opciones: `[path]`, `--url`, `--token`, `--timeout <ms>` (predeterminado 5000).

## Comandos de herramientas

### run-tool

Llama a una herramienta MCP mediante la API HTTP del servidor. La URL y el token provienen de la configuración del proyecto (modo Custom o Cloud) a menos que los sobrescribas.

```bash
unity-mcp-cli run-tool rql-query ./MyGame --input '{"query":"objects | where name == \"Player\" | select path name active"}'
unity-mcp-cli run-tool unity-tool-list ./MyGame --raw
```

| Opción | Descripción |
| --- | --- |
| `<tool-name>` | Herramienta que se va a llamar |
| `[path]` | Proyecto de Unity, usado para detectar la configuración y el puerto |
| `--url <url>`, `--token <token>` | Sobrescrituras que omiten la configuración |
| `--input <json>`, `--input-file <file>` | Argumentos de la herramienta (por defecto `{}`) |
| `--raw` | Salida JSON sin procesar |
| `--timeout <ms>` | Tiempo de espera de la solicitud (por defecto 60000) |

### run-system-tool

Las mismas opciones que `run-tool`, para herramientas del sistema que no se exponen a los clientes MCP (por ejemplo, la generación de skills y el control de sesión).

### exec

Ejecuta C# en el Editor mediante `script-execute` e imprime el resultado. Usa un Editor abierto si hay uno; de lo contrario, inicia un Editor sin interfaz que se mantiene activo para llamadas posteriores y se cierra tras `--idle` segundos.

```bash
unity-mcp-cli exec 'GameObject.FindObjectsOfType<Camera>().Length'
echo 'Application.unityVersion' | unity-mcp-cli exec
```

| Opción | Descripción |
| --- | --- |
| `[code]` | Sentencias de C#; la última expresión es el resultado (o usa `-f` o stdin) |
| `--path <path>` | Proyecto de Unity (por defecto: la carpeta actual) |
| `-f, --file <file>` | Leer el código de un archivo (`-` para stdin) |
| `--using <namespace>` | Namespace adicional, repetible |
| `--include <path>` | Archivo o carpeta `.cs` auxiliar dentro de `.ai-game-dev/snippets`, repetible |
| `--window` | Iniciar el Editor con ventana en lugar de sin interfaz |
| `--idle <seconds>` | Tiempo de inactividad antes de que se cierre un Editor iniciado por `exec` (por defecto 300, 0 para nunca) |
| `--ready-timeout <ms>` | Esperar al Editor (por defecto 300000) |
| `--timeout <ms>` | Tiempo de espera de la llamada a la herramienta |
| `--raw` | JSON de respuesta de la herramienta sin procesar |
| `--url <url>`, `--token <token>` | Sobrescrituras |

Un error de compilación finaliza con el código 1 y señala tus líneas.

## Mantenimiento

### update

Actualiza la CLI a la última versión de npm. `--check` solo comprueba y finaliza con el código 2 cuando hay una actualización disponible. Con `npx` no hay nada que actualizar.

## Uso como biblioteca

El paquete también exporta una API tipada de Node.js (`installPlugin`, `removePlugin`, `configure`, `setupMcp`, `installExtension` y más) que devuelve objetos de resultado en lugar de imprimir. Consulta el [README del paquete en npm](https://www.npmjs.com/package/unity-mcp-cli).

## Páginas relacionadas

- [Instalación](https://ai-game.dev/es/docs/wiki/unity/installation) y [Primeros pasos](https://ai-game.dev/es/docs/wiki/unity/getting-started).
- [Configuración](https://ai-game.dev/es/docs/wiki/unity/configuration#overrides) para las variables de entorno que establece `open`.
- La propia CLI de la aplicación de escritorio, `gamedev`: [CLI de la aplicación](https://ai-game.dev/es/docs/wiki/app/cli).

---

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

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