Referencia de unity-mcp-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#

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:

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#

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.

create-project#

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

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.

install-extension#

Instala una extensión oficial en Packages/manifest.json. Consulta Extensions.

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.

bootstrap-local#

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

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.

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.

setup-skills#

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

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.

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.

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.

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

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.

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

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.

Páginas relacionadas#

• Instalación y Primeros pasos.
• Configuración para las variables de entorno que establece open.
• La propia CLI de la aplicación de escritorio, gamedev: CLI de la aplicación.