Cross-platform CLI for Godot-MCP — the Godot editor addon that bridges LLMs (Claude, Cursor, Copilot, …) with the Godot editor via the Model Context Protocol. Resolve and launch the Godot editor with active MCP connections, run tools, configure AI agents, and manage the godot_mcp addon — all from a single command line.

The CLI is the Godot analog of unity-mcp-cli and unreal-mcp-cli. Backed by ai-game.dev.

Licensed under Apache-2.0.

• :white_check_mark: Open & Connect — build the project's C# assembly and launch the Godot editor with GODOT_MCP_* connection env vars
• :white_check_mark: Install plugin — install the godot_mcp addon end-to-end (download release, add NuGet pins + catalog, enable)
• :white_check_mark: Install extensions — add optional Godot-MCP AI tool-family packages to a project
• :white_check_mark: Remove plugin — disable the godot_mcp addon in project.godot
• :white_check_mark: Configure — enable/disable MCP tools, prompts, and resources
• :white_check_mark: Status check — detect a running Godot editor and probe MCP-server health
• :white_check_mark: Run tools — execute MCP and system tools directly over the server's HTTP API
• :white_check_mark: Setup MCP — write AI-agent MCP-client config for any supported agent
• :white_check_mark: Setup skills — generate Godot-MCP skill files locally (no live editor required)
• :white_check_mark: Wait for ready — poll until the Godot MCP server answers ping
• :white_check_mark: Cross-platform — Windows, macOS, and Linux
• :white_check_mark: Library API — a side-effect-free, typed library surface for embedding

Quick Start

# Install globally
npm install -g godot-cli

# Install the godot_mcp addon into a project
godot-cli install-plugin ./MyGodotProject

# Sign in to the ai-game.dev cloud (OAuth 2.1 device login — once per machine)
godot-cli login

# Open the project (builds C# first, then launches the editor with MCP connection)
godot-cli open ./MyGodotProject

# Wait until the MCP server is ready to accept tool calls
godot-cli wait-for-ready ./MyGodotProject

Or run any command ad-hoc with npx — no global install required:

npx godot-cli install-plugin /path/to/godot/project

Requirements: Node.js ^20.19.0 || >=22.12.0.

Commands

Command	What it does
open [path]	Build the project's C# assembly (so the addon loads on first open — see below), resolve the Godot editor binary, and launch --editor --path <project> with GODOT_MCP_* connection env vars. --no-build skips the build.
build [path]	Build the project's C# assembly (dotnet build) so the godot_mcp addon loads on the next editor open. GDScript-only projects (no .csproj) are a no-op. This is the same build open runs before launching.
run-tool <tool> [path]	POST to <url>/api/tools/<tool> with JSON input.
run-system-tool <tool> [path]	POST to <url>/api/system-tools/<tool> (tools not exposed to MCP clients).
status [path]	Detect a running Godot editor for the project and probe MCP-server health.
wait-for-ready [path]	Poll the MCP server until it answers ping.
login [path]	Authenticate with the ai-game.dev cloud via the OAuth 2.1 device-authorization flow (RFC 8628) — opens a browser, then saves a cloud credential to the shared machine store (~/.ai-game-dev/credentials.json) the editor plugin auto-adopts. See the login section below for its --project / --base-url / --force / --tools-only / --yes flags.
setup-mcp <agent> [path]	Write the agent's MCP-client config pointing at the project-pinned <host>/mcp/p/<pin> URL (so the agent routes to this project's editor). In Cloud mode the config carries this project's key (Authorization: Bearer agd_pk_…). Add --no-pin for the bare <host>/mcp URL, --oauth for a URL-only config, --regenerate-key to replace the key.
setup-skills <agent> [path]	Generate Godot-MCP skill files (a SKILL.md-per-tool-family) under the agent's skills path. --list shows each agent's skills support.
configure [path]	List / enable / disable tools, prompts, and resources in the project-local .godot-mcp/features.json.
close [path]	Gracefully stop the Godot editor running for a project (--force to hard-kill).
install-plugin [path]	Install the godot_mcp addon end-to-end: materialize res://addons/godot_mcp/ (download the matching GitHub release, or --source <path> a local copy), add the required NuGet PackageReferences + the extension-catalog <EmbeddedResource> to the project .csproj, and enable the plugin. Idempotent.
install-extension <id> [path]	Install a Godot-MCP extension (an optional AI-tool-family package) into the project: resolve <id> from the shared catalog, add/update its <PackageReference> in the project .csproj, then rebuild to restore. Idempotent — behaviorally identical to the in-editor dock.
remove-plugin [path]	Disable the godot_mcp addon in project.godot [editor_plugins] (does not delete the addon files).
update	Check npm for a newer godot-cli and install it.

Build before open (open / build)

open builds the project's C# assembly before launching the editor. Godot instantiates an enabled addon's EditorPlugin as soon as the editor loads — so on a fresh first open of a C# project that was never built, no assembly exists yet and Godot fails with Unable to load addon script 'res://addons/godot_mcp/Editor/GodotMcpPlugin.cs' … Disabling the addon. Building first guarantees the assembly is present when the addon is instantiated.

• The build is the same one godot-cli build runs: dotnet build <project>.csproj --configuration Debug.
• GDScript-only projects (no .csproj at the root) are skipped automatically — there is nothing to compile.
• The build runs unconditionally for C# projects; dotnet build is incremental, so an up-to-date project is a fast no-op. Pass --no-build to open to skip it (e.g. you already built, or want to open as fast as possible).
• If the build fails, open does not launch the editor (launching would just reproduce the disable-addon failure); the error is surfaced instead.

Editor resolution (open)

open locates the Godot editor binary in this order:

1. --editor-path <path> (explicit).
2. GODOT_BIN / GODOT4_BIN environment variables.
3. The first matching Godot binary on PATH (the mono build is preferred on Windows).
4. Per-OS common install directories — Windows prefers the mono build; macOS resolves the .app/Contents/MacOS/Godot binary; Linux scans common extracted-binary locations.

Connection env vars

open forwards these to the editor process (names match the addon's GodotMcpConfig):

Flag	Env var
--url <host>	GODOT_MCP_HOST
--cloud-url <url>	GODOT_MCP_CLOUD_URL
--token <token>	GODOT_MCP_TOKEN
--auth None|Required	GODOT_MCP_AUTH_OPTION
--mode Cloud|Custom	GODOT_MCP_CONNECTION_MODE
--log-level <level>	GODOT_MCP_LOG_LEVEL

Server URL resolution (run-tool / status / wait-for-ready)

The server base URL a tool call POSTs to (<base>/api/tools/<name>, or <base>/api/system-tools/<name> for system tools — status / wait-for-ready probe the system tool ping) is resolved as:

1. --url <url> (explicit override).
2. GODOT_MCP_HOST env (Custom-mode host).
3. GODOT_MCP_CLOUD_URL env → the cloud /mcp hub URL (/mcp is appended if absent).
4. GODOT_MCP_CONNECTION_MODE=Cloud → the default cloud hub https://ai-game.dev/mcp.
5. The enrolled project marker (.ai-game-dev/project.json serverTarget, written by install-plugin --enroll): a hosted target routes to its /mcp hub, a localhost target is used verbatim. This makes an enrolled cloud project reachable with zero env config — the persisted cloud credential (per-project store <project>/.ai-game-dev/, then the legacy project sink, then ~/.ai-game-dev/credentials.json) is used automatically, refreshed through expiry.
6. Local fallback: http://localhost:<derived-port>, the deterministic v2 project-path port the editor addon binds locally (a marker portOverride wins over the hash-derived port).

The cloud paths carry the /mcp hub segment so the request reaches the hub rather than the cloud backend (which serves no /api/tools/*). Pass --url http://localhost:<port> to target a local/self-hosted server explicitly.

login

godot-cli login authenticates the editor plugin's cloud connection to ai-game.dev using the OAuth 2.1 device-authorization flow (RFC 8628) — it prints a short user code + verification URL, opens your browser, and polls until you approve:

godot-cli login                       # sign in once per machine (default)
godot-cli login --project ./MyGame    # keep a per-project credential instead
godot-cli login --base-url <url>      # authenticate against a non-default server
godot-cli login --force               # re-authenticate over an existing credential
godot-cli login --tools-only         # CI/automation: tools credential only (no App pickup)
godot-cli login --yes                # non-interactive: confirm replacing another account's credential

• By default the credential is saved to the shared machine store ~/.ai-game-dev/credentials.json (0600 on POSIX / DPAPI on Windows) — sign in once per machine and the Godot editor plugin auto-adopts it, so godot-cli open --mode Cloud connects with no --token.
• The default login signs the whole machine in: the flow requests an agent-scope grant and derives the narrower tools (plugin) credential from it via RFC 8693 token exchange, so every AI-Game-Dev tool on the machine (engine plugins, CLIs, the desktop App) picks the sign-in up.
• --tools-only mints the tools credential only — nothing agent-scoped is stored, the desktop App cannot adopt the sign-in, and the runner shows up as its own revocable device on ai-game.dev. Use it for CI and shared automation runners.
• If the machine already holds a different account's credential, login asks before replacing it (declining revokes the just-minted credential and leaves the store untouched). Pass --yes to confirm non-interactively.
• --project <path> (or the positional [path]) keeps a per-project credential (<path>/.ai-game-dev/credentials.json, gitignored) for per-project accounts. The old per-project sink <path>/.godot-mcp/credentials.json is no longer written — it is still read (and migrated into the machine store on first use) for one release.
• The flow persists the full credential set (access token + rotating refresh token + expiry) — no personal access token (PAT) is ever minted. On any failure nothing is written, so an existing credential survives a denied / expired / network error intact. Commands refresh an expired access token automatically (via @baizor/gamedev-cli-core), so a signed-in machine stays signed in without re-running login.

setup-skills

godot-cli setup-skills <agent> [path] generates AI-agent skill files for a Godot project under the selected agent's skills path (e.g. Claude Code's .claude/skills). Use --list to see every agent and its skills support.

godot-cli setup-skills claude-code            # generate into ./.claude/skills
godot-cli setup-skills cursor ./MyGame        # generate into MyGame/.cursor/skills
godot-cli setup-skills --list                 # list agents + their skills paths

The command writes a SKILL.md-per-tool-family directory (a godot-mcp/ overview plus one per family: godot-mcp-node, godot-mcp-scene, godot-mcp-resource, …) describing the godot_mcp addon's tool families. It is idempotent — re-running rewrites the same bytes.

Unlike the Unity CLI — which POSTs to a running editor's /api/system-tools/unity-skill-generate endpoint — the Godot CLI generates the files locally from a built-in catalog, so no server and no running editor are required. (The addon now also exposes godot-skill-generate on /api/system-tools/, but that path needs a booted editor; local generation is the server-less one.) (The addon additionally auto-generates skills in-process on plugin boot via GodotMcpConnection.Start → GenerateSkillFilesIfNeeded; the CLI command is the server-less, scriptable path that does not need a live editor.)

install-plugin

godot-cli install-plugin [path] is a real installer — it makes a from-scratch terminal install produce a working project, in one idempotent command:

godot-cli install-plugin ./MyGodotProject                      # download the matching release + install
godot-cli install-plugin --version 0.11.1 ./MyGodotProject     # pin a specific addon release
godot-cli install-plugin --source ./Godot-MCP/addons/godot_mcp ./MyGodotProject   # offline / dev copy

It performs four steps:

1. Materialize res://addons/godot_mcp/. By default it downloads godot-mcp-addon-<version>.zip over HTTPS from github.com only (the IvanMurzak/Godot-MCP release v<version>; the version defaults to the CLI's own version). Non-github.com hosts and plain http are rejected. With --source <path> it copies the addon from a local directory instead (no network) — <path> may be a directory that is addons/godot_mcp or one that contains it.
2. Add the NuGet packages the addon needs (com.IvanMurzak.ReflectorNet, com.IvanMurzak.McpPlugin) to the project's .csproj, idempotently — adding when missing, reconciling a stale version, and leaving a correct pin untouched. The versions are single-sourced from the addon's own Godot-MCP.csproj pins, so the scaffold can never drift.
3. Embed the extension catalog (<EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />) into the project's .csproj, idempotently. Without it the addon's extension registry reads no catalog at editor runtime and the Extensions panel is empty. Single-sourced + parity-tested against the addon csproj alongside the pins.
4. Enable the plugin in project.godot [editor_plugins].

It is library-safe (returns a { kind: 'success' | 'failure' } union; never throws past the public boundary) and idempotent — re-running on an already-installed project reports no change.

install-extension

godot-cli install-extension <id> [path] installs an optional Godot-MCP extension (a package that adds more AI tool families) into a Godot C# project — the terminal/library channel for the same install the in-editor Extensions dock performs:

godot-cli install-extension com.IvanMurzak.Godot.MCP.ProBuilder ./MyGodotProject   # add/update the PackageReference
godot-cli install-extension "ProBuilder Tools"                                      # resolve by name; default cwd
godot-cli install-extension com.IvanMurzak.Godot.MCP.ProBuilder --version 1.3.0     # override the catalog pin

• Resolves <id> against the shared extension catalog (addons/godot_mcp/extensions.catalog.json — the single source of truth the dock, the CLI, and the app all consume), matching by package id (then name), case-insensitive.
• Read-modify-writes a <PackageReference Include="<packageId>" Version="<version>" /> into the project's root .csproj: added when absent, version bumped only when the catalog (or --version) pins a newer version, and a no-op when already up to date — then asks you to rebuild (godot-cli build) so Godot restores + compiles the new package.
• Behaviorally identical to the dock's ExtensionInstaller (the same add / update / no-op + numeric version-compare rules; verified by a shared scenario set on both sides).

The catalog ships empty until the first Godot-MCP extension package is published, so every <id> is currently reported as an unknown extension — there is nothing to install yet.

Library API

The package also exports a side-effect-free library (the . entry):

import { openProject, runTool, setupMcp, installPlugin, installExtension } from 'godot-cli';

// The shared extension catalog + lookup helpers are exported too, so a GUI (the app)
// can render the same list the dock + CLI install from:
import { EXTENSIONS_CATALOG, findExtension } from 'godot-cli';

Every function returns a discriminated union ({ kind: 'success', ... } / { kind: 'failure', error }) and never throws past the public boundary.

Development

npm install
npm run build   # tsc → dist/ (ESM)
npm test        # vitest

Supported AI Agents

godot-cli writes ready-to-use MCP client configs for every major AI coding agent — run godot-cli setup-mcp <agent> [path] to wire one up (and godot-cli setup-skills <agent> [path] to generate its skill files). Use --list on either command to see every supported agent.

godot-cli setup-mcp --list                    # list every supported agent id
godot-cli setup-mcp claude-code ./MyGame      # write the agent's MCP client config (pinned to this project)
godot-cli setup-mcp claude-code ./MyGame --no-pin   # write the bare, unpinned <host>/mcp URL instead
godot-cli setup-mcp claude-code ./MyGame --oauth    # URL-only: the agent signs in with its own OAuth
godot-cli setup-mcp claude-code ./MyGame --regenerate-key   # new project key; the old one is revoked

In Cloud mode setup-mcp writes a project key into the agent config for every agent: Authorization: Bearer agd_pk_… (Codex: http_headers). A project key never expires, is bound to this project's pin (it cannot reach any other project on your account), and is created once per project with your machine sign-in (godot-cli login), then reused from ~/.ai-game-dev/project-keys.json. --regenerate-key replaces it and revokes the old one. Without a machine sign-in (or while the server cannot issue keys) the config is URL-only and the agent authenticates with its own OAuth; --oauth asks for that URL-only config explicitly. An explicit --token always wins. A local server config (--url http://localhost:…) never carries a project key.

For the full Godot-MCP project documentation, see the main README. Backed by ai-game.dev.