# godot-cli リファレンス — Godot · AI Game Developer Wiki

Godot MCP 向け godot-cli の全コマンドとフラグを解説します。install-plugin、login、setup-mcp から open、exec、run-tool、configure、install-extension まで。

このページは英語から機械翻訳されています。[英語の原文を読む](https://ai-game.dev/docs/wiki/godot/cli)。

`godot-cli` は Godot MCP 用のコマンドラインツールで、npm で公開されています。アドオンをインストールし、サインインし、AI エージェントの設定を書き込み、適切な接続設定でエディタをビルドして開き、スクリプトからツールを呼び出します。このページでは `godot-cli` 0.34.0 のすべてのコマンドとそのフラグを一覧します。

## インストールと基本

```bash
npm install -g godot-cli
godot-cli --help
godot-cli <command> --help
```

Node.js `^20.19.0` または `>=22.12.0` が必要で、Windows、macOS、Linux で動作します。インストールせずに任意のコマンドを実行することもできます: `npx godot-cli <command>`。

ほとんどのコマンドはプロジェクトフォルダを省略可能な位置引数 `[path]`（または `--path <path>`）として受け取り、デフォルトは現在のフォルダです。すべてのコマンドは診断出力用に `-v` / `--verbose` を受け付けます。

## コマンド一覧

| コマンド | 内容 |
| --- | --- |
| `install-plugin [path]` | アドオンをインストールし、`.csproj` をパッチし、プラグインを有効化します。 |
| `install-extension <id> [path]` | `.csproj` に拡張機能パッケージを追加または更新します。 |
| `remove-plugin [path]` | `project.godot` 内でアドオンを無効化します（ファイルは残ります）。 |
| `create-project [path]` | 最小限の Godot 4 プロジェクトを生成します。 |
| `build [path]` | プロジェクトの C# アセンブリをビルドします。 |
| `open [path]` | ビルドしてから、接続設定付きで Godot エディタを開きます。 |
| `close [path]` | プロジェクトで実行中の Godot エディタを停止します。 |
| `exec [code]` | `script-execute` を通じてエディタ内で C# を実行します。 |
| `login [path]` | デバイスフローで ai-game.dev にサインインします。 |
| `setup-mcp <agent> [path]` | AI エージェントの MCP 設定を書き込みます。 |
| `setup-skills <agent> [path]` | AI エージェント用のスキルファイルを生成します。 |
| `configure [path]` | ツール、プロンプト、リソースの表示/非表示を設定します。 |
| `run-tool <tool> [path]` | HTTP 経由で MCP ツールを呼び出します。 |
| `run-system-tool <tool> [path]` | HTTP 経由でシステムツールを呼び出します。 |
| `status [path]` | エディタと MCP サーバーを確認します。 |
| `wait-for-ready [path]` | エディタが `ping` に応答するまで待機します。 |
| `update` | `godot-cli` 自体を更新します。 |

## install-plugin

`godot_mcp` アドオンを一通りインストールします: GitHub からアドオンのリリースをダウンロード（またはローカルのものをコピー）し、`.csproj` に NuGet の `PackageReference` と拡張機能カタログの `<EmbeddedResource>` を追加し、`EnableDynamicLoading` を設定し、`project.godot` でプラグインを有効化します。再実行しても安全です。

| フラグ | 意味 |
| --- | --- |
| `--source <path>` | ダウンロードする代わりにローカルフォルダからアドオンをコピーします（オフライン、開発、CI 向け）。 |
| `--version <x.y.z>` | ダウンロードするアドオンのリリース。デフォルトは CLI のバージョン。`--source` 指定時は無視されます。 |
| `--with-server` | 対応する `gamedev-mcp-server` バイナリもダウンロードし、リリースのチェックサムで検証します。 |
| `--server-source <path>` | ローカルフォルダまたは `.zip` からサーバーをインストールします。`--with-server` を暗黙的に有効にします。 |
| `--server-version <x.y.z>` | ダウンロードするサーバーのバージョン。デフォルトはアドオンが固定しているサーバーバージョン。 |
| `--enroll <code>` | エージェント登録コードを引き換えます（ブラウザなしでプラグインにサインインします）。 |
| `--enroll-stdin` | 登録コードを stdin から読み取り、シェル履歴に残らないようにします。 |
| `--base-url <url>` | 登録コードを引き換えるクラウド URL。デフォルトは `https://ai-game.dev`。 |

```bash
godot-cli install-plugin ./MyGodotProject
godot-cli install-plugin --version 0.34.0 ./MyGodotProject
godot-cli install-plugin --source ./Godot-MCP/addons/godot_mcp ./MyGodotProject
```

## install-extension

`godot-cli install-extension <id> [path]` は拡張機能カタログで id（パッケージ id または名前）を解決し、その `<PackageReference>` を追加または更新します。`--version <x.y.z>` を指定すると、最新の安定版ではなく正確なバージョンを要求します。その後 `godot-cli build` を実行してください。詳しくは [Extensions](https://ai-game.dev/ja/docs/wiki/godot/extensions) を参照してください。

## remove-plugin

`project.godot` の `[editor_plugins]` セクションでアドオンを無効化します。`addons/godot_mcp/` や `.csproj` のエントリは削除しません。

## create-project

最小限の Godot 4 プロジェクト（`project.godot` と `icon.svg`）を生成します。既存の Godot、Unity、Unreal プロジェクトは上書きしません。

| フラグ | 意味 |
| --- | --- |
| `--dotnet` | `Godot.NET.Sdk` の C# `.csproj` も作成します（Godot MCP に必要）。 |
| `--name <name>` | プロジェクト名。デフォルトはフォルダ名。 |

## build

プロジェクトの `.csproj` に対して `dotnet build` を実行し、次回エディタを開いたときにアドオンが読み込まれるようにします。`.csproj` がないプロジェクトはスキップされます。

| フラグ | 意味 |
| --- | --- |
| `--configuration <cfg>` | MSBuild 構成。デフォルトは `Debug`。 |
| `--dotnet-path <path>` | `PATH` 上のものではなく、指定した `dotnet` 実行ファイルを使用します。 |

## open

C# アセンブリをビルドし、Godot エディタを見つけてプロジェクトを開きます。ビルドが失敗した場合、エディタは起動しません。エディタは次の順序で検索されます: `--editor-path`、`GODOT_BIN` または `GODOT4_BIN` 環境変数、`PATH` 上の Godot バイナリ（Windows では .NET ビルドが優先されます）、そして一般的なインストールフォルダ。

| フラグ | 意味 |
| --- | --- |
| `--editor-path <path>` | 使用する Godot エディタの実行ファイル。 |
| `--no-build` | C# ビルドをスキップします。 |
| `--build-configuration <cfg>` | プリオープンビルドの構成。既定は `Debug`。 |
| `--no-connect` | `GODOT_MCP_*` 接続変数を使わずに開きます。 |
| `--mode <Cloud or Custom>` | `GODOT_MCP_CONNECTION_MODE` を設定します。 |
| `--url <url>` | `GODOT_MCP_HOST` を設定します。 |
| `--cloud-url <url>` | `GODOT_MCP_CLOUD_URL` を設定します。 |
| `--token <token>` | `GODOT_MCP_TOKEN` を設定します。 |
| `--auth <None or Required>` | `GODOT_MCP_AUTH_OPTION` を設定します。 |
| `--log-level <level>` | `GODOT_MCP_LOG_LEVEL` (`Trace`、`Debug`、`Info`、`Warning`、`Error`、`None`) を設定します。 |
| `--headless` | プロジェクトのローカルサーバー上でウィンドウなしのエディターを起動し、準備が整うまで待機します。実行中のものがあれば再利用します。 |
| `--idle-timeout <seconds>` | `--headless` 指定時: ツール呼び出しがない状態がこの秒数続いたら終了します (`0` = 終了しない)。 |
| `--ready-timeout <ms>` | `--headless` 指定時: エディターが準備完了になるまで待つ時間。 |

## close

プロジェクトで実行中の Godot エディターを安全に停止します。

| フラグ | 意味 |
| --- | --- |
| `--timeout <seconds>` | 正常終了を待つ時間。既定は 30。 |
| `--force` | 時間内に終了しない場合、エディターを強制終了します。 |
| `--owned-only` | `godot-cli` が起動したエディター (`exec`、`open --headless`) のみを閉じ、自分で起動したエディターは閉じません。開いているシーンは先に保存されます。 |
| `--token <token>` | `--owned-only` 指定時: ベアラートークン。既定は `GODOT_MCP_TOKEN`。 |

## exec

`script-execute` ツールを使ってプロジェクトのエディターで C# を実行します。コードは単純な文の並びで、最後の式が結果になります。プロジェクトのエディターが実行中であれば再利用されます (自分のエディターが Custom モードで、ローカルサーバーが起動している必要があります)。そうでない場合、`exec` はプロジェクトをビルドし、ローカルサーバーに接続したヘッドレスエディターを起動します。このエディターは呼び出しがないまま `--idle` 秒経過すると終了します (既定は 300)。

```bash
godot-cli exec '1 + 2' --path ./MyGodotProject
godot-cli exec -f snippet.cs --using MyGame.Gameplay
godot-cli exec 'Helper.Twice(21)' --include helpers
```

| フラグ | 意味 |
| --- | --- |
| `--path <path>` | プロジェクトフォルダー。 |
| `-f, --file <file>` | ファイルからコードを読み込みます (標準入力には `-`)。 |
| `--using <namespace>` | 追加の名前空間。複数回指定できます。 |
| `--include <path>` | `<project>/.ai-game-dev/snippets` 配下のヘルパー `.cs` ファイルまたはフォルダー。複数回指定できます。 |
| `--window` | ヘッドレスではなくウィンドウ付きでエディターを起動します。 |
| `--idle <seconds>` | 起動したエディターが終了するまでのアイドル時間 (`0` = 終了しない)。 |
| `--ready-timeout <ms>` | 起動したエディターを待つ時間。 |
| `--timeout <ms>` | ツール呼び出しのタイムアウト。既定は 310000。 |
| `--no-build` | エディターを起動する前にビルドしません。 |
| `--editor-path <path>` | Godot エディターの実行ファイル。 |
| `--url <url>` | ローカル MCP サーバーの URL。既定: プロジェクトのローカルポート。 |
| `--token <token>` | ベアラートークン。既定は `GODOT_MCP_TOKEN`。 |
| `--raw` | ツールレスポンスの生 JSON を出力します。 |

コンパイルエラーはスニペットの行を指し示し、コード 1 で終了します。

## login

OAuth 2.1 デバイスフローで ai-game.dev にサインインし、認証情報を `~/.ai-game-dev/credentials.json` に保存します。エディターはこのファイルを読み取ります。詳細は [AI クライアントの接続](https://ai-game.dev/ja/docs/wiki/godot/connecting-ai-clients#device-flow) を参照してください。

| フラグ | 意味 |
| --- | --- |
| `--project <path>` | 代わりに `<path>/.ai-game-dev/` 配下にプロジェクト単位の認証情報を保存します。 |
| `--base-url <url>` | 別のサーバーに対してサインインします。既定は `https://ai-game.dev`。 |
| `--force` | 認証情報が存在しても再びサインインします。 |
| `--tools-only` | CI モード: デスクトップアプリが読み取らないツール専用の認証情報を作成します。 |
| `--yes` | 確認なしで別アカウントの認証情報を置き換えます。 |

## setup-mcp

`godot-cli setup-mcp <agent> [path]` はエージェントの MCP 設定を書き込み、既定ではこのプロジェクトに固定します。エージェント ID と設定ファイルは [AI クライアントの接続](https://ai-game.dev/ja/docs/wiki/godot/connecting-ai-clients#agents) に記載されています。

| フラグ | 意味 |
| --- | --- |
| `--list` | すべてのエージェント ID を一覧表示します。 |
| `--url <url>` | サーバーホストの上書き。たとえばローカルサーバー。 |
| `--token <token>` | トークンの上書き。既定は `GODOT_MCP_TOKEN`。 |
| `--no-pin` | 固定 URL ではなく通常の `/mcp` URL を書き込みます。 |
| `--oauth` | Cloud: URL のみの設定。エージェントは自身の OAuth でサインインします。 |
| `--regenerate-key` | Cloud: 新しいプロジェクトキーを作成し、古いキーを取り消します。 |

## setup-skills

`godot-cli setup-skills <agent> [path]` はアドオンのツールファミリーごとの `SKILL.md` ファイルをエージェントのスキルフォルダー (たとえば `.claude/skills`) に書き込みます。実行中のエディターは不要です。`--list` で各エージェントのスキル対応状況を表示します。

## configure

MCP クライアントに表示されるツール、プロンプト、リソースを `.godot-mcp/features.json` で一覧表示または変更します。非表示の項目も名前で呼び出せば実行されます。

| フラグ | 意味 |
| --- | --- |
| `--list` | 現在の設定を表示します。 |
| `--enable-tools <names>` / `--disable-tools <names>` | ツールを表示または非表示にします (カンマ区切り)。 |
| `--enable-all-tools` / `--disable-all-tools` | すべてのツールを表示または非表示にします。 |
| `--enable-prompts <names>` / `--disable-prompts <names>` | プロンプトを表示または非表示にします。 |
| `--enable-all-prompts` / `--disable-all-prompts` | すべてのプロンプトを表示または非表示にします。 |
| `--enable-resources <names>` / `--disable-resources <names>` | リソースを表示または非表示にします。 |
| `--enable-all-resources` / `--disable-all-resources` | すべてのリソースを表示または非表示にします。 |
| `--agent <id>` | 管理対象のサーバーバイナリ経由でエージェントを設定します（`install-plugin --with-server` が必要）。 |
| `--url <url>` | `--agent` と併用: サーバー URL を上書きします。 |

## run-tool と run-system-tool

サーバーの HTTP API 経由でツールを直接呼び出します: `run-tool` は `/api/tools/<tool>` に、`run-system-tool` は `/api/system-tools/<tool>` に POST します（`ping` など、MCP クライアントから隠されているツール向け）。

```bash
godot-cli run-tool rql-query ./MyGodotProject --input '{"query":"nodes | select name class"}'
godot-cli run-system-tool ping ./MyGodotProject
```

| フラグ | 意味 |
| --- | --- |
| `--url <url>` | サーバーのベース URL。 |
| `--token <token>` | Bearer トークン。デフォルトは `GODOT_MCP_TOKEN`。 |
| `--input <json>` | ツールの引数を JSON 文字列で指定します。 |
| `--input-file <file>` | JSON 引数をファイルから読み込みます。 |
| `--raw` | 生の JSON を出力します。 |
| `--timeout <ms>` | リクエストのタイムアウト。デフォルトは 60000。 |

`--url` を指定しない場合、サーバーは `GODOT_MCP_HOST`、次に `GODOT_MCP_CLOUD_URL`、次に `GODOT_MCP_CONNECTION_MODE=Cloud` のときはクラウド、次にプロジェクトに登録済みのサーバー、最後にプロジェクトのローカルポートの順に選択されます。

## status と wait-for-ready

`status` はプロジェクトで実行中のエディタを検出し、サーバーをプローブします（`--url`、`--token`、`--timeout <ms>`、デフォルト 5000）。`wait-for-ready` はエディタが応答するまで `ping` をポーリングします（`--url`、`--token`、`--timeout <ms>` デフォルト 120000、`--interval <ms>` デフォルト 3000）。`open` の後のスクリプトで使用します。

## update

`godot-cli update` は npm で新しい `godot-cli` を確認してインストールします。`--check` はレポートのみ行います。

## 関連情報

- AI Game Dev アプリには独自の `gamedev` CLI があります: [App CLI](https://ai-game.dev/ja/docs/wiki/app/cli)。
- Unity と Unreal には `unity-mcp-cli` と `unreal-mcp-cli` があります: [Unity MCP](https://ai-game.dev/ja/docs/wiki/unity) と [Unreal MCP](https://ai-game.dev/ja/docs/wiki/unreal) の wiki を参照してください。

---

Source (HTML): https://ai-game.dev/ja/docs/wiki/godot/cli

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