Referencia de godot-cli
Todos los comandos y flags de godot-cli para Godot MCP, desde install-plugin, login y setup-mcp hasta open, exec, run-tool, configure e install-extension.
godot-cli es la herramienta de línea de comandos para Godot MCP, publicada en npm. Instala el addon, inicia tu sesión, escribe las configuraciones de los agentes de IA, compila y abre el editor con los ajustes de conexión correctos, y llama a herramientas desde scripts. Esta página enumera todos los comandos de godot-cli 0.34.0 con sus flags.
Instalación y conceptos básicos
npm install -g godot-cli
godot-cli --help
godot-cli <command> --helpRequiere Node.js ^20.19.0 o >=22.12.0 y funciona en Windows, macOS y Linux. También puedes ejecutar cualquier comando sin instalarlo: npx godot-cli <command>.
La mayoría de los comandos aceptan la carpeta del proyecto como un [path] posicional opcional (o --path <path>) y usan por defecto la carpeta actual. Todos los comandos aceptan -v / --verbose para obtener salida de diagnóstico.
Resumen de comandos
| Comando | Qué hace |
|---|---|
install-plugin [path] | Instala el addon, modifica el .csproj y habilita el plugin. |
install-extension <id> [path] | Añade o actualiza un paquete de extensión en el .csproj. |
remove-plugin [path] | Deshabilita el addon en project.godot (los archivos se conservan). |
create-project [path] | Genera la estructura de un proyecto mínimo de Godot 4. |
build [path] | Compila el ensamblado C# del proyecto. |
open [path] | Compila y, después, abre el editor de Godot con los ajustes de conexión. |
close [path] | Detiene el editor de Godot que está en ejecución para el proyecto. |
exec [code] | Ejecuta C# en el editor mediante script-execute. |
login [path] | Inicia sesión en ai-game.dev con el flujo de dispositivo. |
setup-mcp <agent> [path] | Escribe la configuración MCP de un agente de IA. |
setup-skills <agent> [path] | Genera archivos de skills para un agente de IA. |
configure [path] | Muestra u oculta herramientas, prompts y recursos. |
run-tool <tool> [path] | Llama a una herramienta MCP por HTTP. |
run-system-tool <tool> [path] | Llama a una herramienta del sistema por HTTP. |
status [path] | Comprueba el editor y el servidor MCP. |
wait-for-ready [path] | Espera hasta que el editor responda a ping. |
update | Actualiza godot-cli en sí. |
install-plugin
Instala el addon godot_mcp de principio a fin: descarga la versión del addon desde GitHub (o copia una local), añade las PackageReference de NuGet y el <EmbeddedResource> del catálogo de extensiones al .csproj, establece EnableDynamicLoading y habilita el plugin en project.godot. Se puede volver a ejecutar sin problema.
| Flag | Significado |
|---|---|
--source <path> | Copia el addon desde una carpeta local en lugar de descargarlo (sin conexión, desarrollo, CI). |
--version <x.y.z> | Versión del addon que se descargará. Por defecto, la versión de la CLI. Se ignora con --source. |
--with-server | También descarga el binario gamedev-mcp-server correspondiente, verificado con las sumas de comprobación de la versión. |
--server-source <path> | Instala el servidor desde una carpeta local o un .zip. Implica --with-server. |
--server-version <x.y.z> | Versión del servidor que se descargará. Por defecto, la versión del servidor fijada por el addon. |
--enroll <code> | Canjea un código de enrolamiento de agente (inicia sesión en el plugin sin navegador). |
--enroll-stdin | Lee el código de enrolamiento desde stdin, para que no quede en el historial del shell. |
--base-url <url> | URL de la nube contra la que se canjea el código de enrolamiento. Por defecto https://ai-game.dev. |
godot-cli install-plugin ./MyGodotProject
godot-cli install-plugin --version 0.34.0 ./MyGodotProject
godot-cli install-plugin --source ./Godot-MCP/addons/godot_mcp ./MyGodotProjectinstall-extension
godot-cli install-extension <id> [path] resuelve el id (id de paquete o nombre) en el catálogo de extensiones y añade o actualiza su <PackageReference>. --version <x.y.z> solicita una versión exacta en lugar de la última estable. Ejecuta godot-cli build después. Consulta Extensions.
remove-plugin
Deshabilita el addon en la sección [editor_plugins] de project.godot. No elimina addons/godot_mcp/ ni las entradas del .csproj.
create-project
Genera la estructura de un proyecto mínimo de Godot 4 (project.godot e icon.svg). Se niega a sobrescribir un proyecto existente de Godot, Unity o Unreal.
| Flag | Significado |
|---|---|
--dotnet | También crea un .csproj de C# con Godot.NET.Sdk (necesario para Godot MCP). |
--name <name> | Nombre del proyecto. Por defecto, el nombre de la carpeta. |
build
Ejecuta dotnet build en el .csproj del proyecto para que el addon se cargue la próxima vez que se abra el editor. Los proyectos sin .csproj se omiten.
| Flag | Significado |
|---|---|
--configuration <cfg> | Configuración de MSBuild. Por defecto Debug. |
--dotnet-path <path> | Usa este ejecutable dotnet en lugar del que está en PATH. |
open
Compila el ensamblado C# , localiza el editor de Godot y abre el proyecto. Si la compilación falla, el editor no se inicia. El editor se busca en este orden: --editor-path, la variable de entorno GODOT_BIN o GODOT4_BIN, un binario de Godot en PATH (en Windows se prefiere la compilación .NET) y, por último, las carpetas de instalación habituales.
| Flag | Significado |
|---|---|
--editor-path <path> | Ejecutable del editor de Godot que se usará. |
--no-build | Omite la compilación de C#. |
--build-configuration <cfg> | Configuración para la compilación de preapertura. Por defecto, Debug. |
--no-connect | Abrir sin ninguna variable de conexión GODOT_MCP_*. |
--mode <Cloud or Custom> | Establece GODOT_MCP_CONNECTION_MODE. |
--url <url> | Establece GODOT_MCP_HOST. |
--cloud-url <url> | Establece GODOT_MCP_CLOUD_URL. |
--token <token> | Establece GODOT_MCP_TOKEN. |
--auth <None or Required> | Establece GODOT_MCP_AUTH_OPTION. |
--log-level <level> | Establece GODOT_MCP_LOG_LEVEL (Trace, Debug, Info, Warning, Error, None). |
--headless | Inicia un editor sin ventana en el servidor local del proyecto y espera hasta que esté listo. Reutiliza uno que ya se esté ejecutando. |
--idle-timeout <seconds> | Con --headless: salir tras este número de segundos sin llamadas a herramientas (0 = nunca). |
--ready-timeout <ms> | Con --headless: cuánto tiempo esperar a que el editor esté listo. |
close
Detiene de forma ordenada el editor de Godot que se ejecuta para el proyecto.
| Opción | Significado |
|---|---|
--timeout <seconds> | Cuánto tiempo esperar a un cierre ordenado. Por defecto, 30. |
--force | Finalizar el proceso del editor si no se cierra a tiempo. |
--owned-only | Cerrar solo un editor que haya iniciado godot-cli (exec, open --headless), nunca el tuyo. Primero guarda las escenas abiertas. |
--token <token> | Con --owned-only: token bearer. Por defecto, GODOT_MCP_TOKEN. |
exec
Ejecuta C# en el editor del proyecto con la herramienta script-execute. El código son sentencias simples; la última expresión es el resultado. Si hay un editor del proyecto en ejecución, se reutiliza (el tuyo debe estar en modo Custom con su servidor local iniciado). En caso contrario, exec compila el proyecto e inicia un editor headless conectado a un servidor local, que se cierra tras --idle segundos sin llamadas (por defecto, 300).
godot-cli exec '1 + 2' --path ./MyGodotProject
godot-cli exec -f snippet.cs --using MyGame.Gameplay
godot-cli exec 'Helper.Twice(21)' --include helpers| Opción | Significado |
|---|---|
--path <path> | Carpeta del proyecto. |
-f, --file <file> | Leer el código desde un archivo (- para stdin). |
--using <namespace> | Espacio de nombres adicional. Se puede repetir. |
--include <path> | Archivo o carpeta .cs de ayuda bajo <project>/.ai-game-dev/snippets. Se puede repetir. |
--window | Iniciar el editor con ventana en lugar de headless. |
--idle <seconds> | Tiempo de inactividad antes de que se cierre un editor iniciado (0 = nunca). |
--ready-timeout <ms> | Cuánto tiempo esperar a un editor iniciado. |
--timeout <ms> | Tiempo de espera de la llamada a la herramienta. Por defecto, 310000. |
--no-build | No compilar antes de iniciar un editor. |
--editor-path <path> | Ejecutable del editor de Godot. |
--url <url> | URL del servidor MCP local. Por defecto: el puerto local del proyecto. |
--token <token> | Token bearer. Por defecto, GODOT_MCP_TOKEN. |
--raw | Imprime el JSON de respuesta sin procesar de la herramienta. |
Un error de compilación señala la línea del snippet y sale con código 1.
login
Inicia sesión en ai-game.dev con el flujo de dispositivo OAuth 2.1 y guarda la credencial en ~/.ai-game-dev/credentials.json, que el editor recoge. Consulta Conectar clientes de IA.
| Opción | Significado |
|---|---|
--project <path> | Guardar en su lugar una credencial por proyecto en <path>/.ai-game-dev/. |
--base-url <url> | Iniciar sesión contra otro servidor. Por defecto, https://ai-game.dev. |
--force | Iniciar sesión de nuevo aunque ya exista una credencial. |
--tools-only | Modo CI: crear una credencial solo para herramientas que la aplicación de escritorio no recoge. |
--yes | Reemplazar la credencial de otra cuenta sin preguntar. |
setup-mcp
godot-cli setup-mcp <agent> [path] escribe la configuración MCP del agente, fijada a este proyecto por defecto. Los ids de agente y los archivos de configuración se enumeran en Conectar clientes de IA.
| Opción | Significado |
|---|---|
--list | Enumera todos los ids de agente. |
--url <url> | Sustitución del host del servidor, por ejemplo, un servidor local. |
--token <token> | Sustitución del token. Por defecto, GODOT_MCP_TOKEN. |
--no-pin | Escribir la URL /mcp simple en lugar de la fijada. |
--oauth | Nube: configuración solo de URL; el agente inicia sesión con su propio OAuth. |
--regenerate-key | Nube: crear una nueva clave de proyecto y revocar la anterior. |
setup-skills
godot-cli setup-skills <agent> [path] escribe archivos SKILL.md para las familias de herramientas del addon en la carpeta de skills del agente (por ejemplo, .claude/skills). No necesita un editor en ejecución. --list muestra la compatibilidad de skills de cada agente.
configure
Enumera o cambia qué herramientas, prompts y recursos ven los clientes MCP, en .godot-mcp/features.json. Los elementos ocultos siguen ejecutándose cuando se llaman por nombre.
| Opción | Significado |
|---|---|
--list | Mostrar la configuración actual. |
--enable-tools <names> / --disable-tools <names> | Mostrar u ocultar herramientas (separadas por comas). |
--enable-all-tools / --disable-all-tools | Mostrar u ocultar todas las herramientas. |
--enable-prompts <names> / --disable-prompts <names> | Mostrar u ocultar prompts. |
--enable-all-prompts / --disable-all-prompts | Mostrar u ocultar todos los prompts. |
--enable-resources <names> / --disable-resources <names> | Mostrar u ocultar recursos. |
--enable-all-resources / --disable-all-resources | Mostrar u ocultar todos los recursos. |
--agent <id> | Configura un agente mediante el binario del servidor gestionado (requiere install-plugin --with-server). |
--url <url> | Con --agent: sobrescribe la URL del servidor. |
run-tool y run-system-tool
Llama a una herramienta directamente a través de la API HTTP del servidor: run-tool envía una petición POST a /api/tools/<tool> y run-system-tool a /api/system-tools/<tool> (herramientas ocultas para los clientes MCP, como ping).
godot-cli run-tool rql-query ./MyGodotProject --input '{"query":"nodes | select name class"}'
godot-cli run-system-tool ping ./MyGodotProject| Opción | Significado |
|---|---|
--url <url> | URL base del servidor. |
--token <token> | Token Bearer. Por defecto, GODOT_MCP_TOKEN. |
--input <json> | Argumentos de la herramienta como cadena JSON. |
--input-file <file> | Lee los argumentos JSON desde un archivo. |
--raw | Imprime el JSON sin procesar. |
--timeout <ms> | Tiempo de espera de la petición. Por defecto, 60000. |
Sin --url, el servidor se elige a partir de GODOT_MCP_HOST, luego de GODOT_MCP_CLOUD_URL, después la nube cuando GODOT_MCP_CONNECTION_MODE=Cloud, luego el servidor inscrito del proyecto y, por último, el puerto local del proyecto.
status y wait-for-ready
status detecta un editor en ejecución para el proyecto y sondea el servidor (--url, --token, --timeout <ms>, por defecto 5000). wait-for-ready consulta ping repetidamente hasta que el editor responde (--url, --token, --timeout <ms>, por defecto 120000; --interval <ms>, por defecto 3000). Úsalo en scripts después de open.
update
godot-cli update busca en npm una versión más reciente de godot-cli y la instala; --check solo informa.
Relacionado
- La aplicación AI Game Dev tiene su propia CLI
gamedev: App CLI. - Unity y Unreal tienen
unity-mcp-cliyunreal-mcp-cli: consulta las wikis de Unity MCP y Unreal MCP.