godot-cli 參考
Godot MCP 的每個 godot-cli 指令與旗標，從 install-plugin、login、setup-mcp 到 open、exec、run-tool、configure 與 install-extension。
godot-cli 是 Godot MCP 的命令列工具，發佈於 npm。它會安裝 addon、讓你登入、寫入 AI 代理程式設定、建置並以正確的連線設定開啟編輯器，還能從腳本呼叫工具。本頁列出 godot-cli 0.34.0 中每個指令及其旗標。
安裝與基本用法
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] | 安裝 addon、修補 .csproj、啟用外掛。 |
install-extension <id> [path] | 在 .csproj 中新增或更新擴充套件。 |
remove-plugin [path] | 在 project.godot 中停用 addon（檔案保留）。 |
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 代理程式產生 skill 檔案。 |
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 addon：從 GitHub 下載 addon 發行版（或複製本機版本）、將 NuGet PackageReference 與擴充套件目錄 <EmbeddedResource> 加入 .csproj、設定 EnableDynamicLoading，並在 project.godot 中啟用外掛。可安全重複執行。
| 旗標 | 說明 |
|---|---|
--source <path> | 從本機資料夾複製 addon，而非下載（離線、開發、CI 使用）。 |
--version <x.y.z> | 要下載的 addon 發行版。預設為 CLI 的版本。搭配 --source 時忽略。 |
--with-server | 同時下載對應的 gamedev-mcp-server 執行檔，並依發行版 checksum 驗證。 |
--server-source <path> | 從本機資料夾或 .zip 安裝伺服器。隱含 --with-server。 |
--server-version <x.y.z> | 要下載的伺服器版本。預設為 addon 指定的伺服器版本。 |
--enroll <code> | 兌換代理程式註冊碼（不需瀏覽器即可讓外掛登入）。 |
--enroll-stdin | 從 stdin 讀取註冊碼，避免留在 shell 歷史紀錄中。 |
--base-url <url> | 用來兌換註冊碼的雲端 URL。預設為 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] 會在擴充套件目錄中解析該 id（套件 id 或名稱），並新增或更新其 <PackageReference>。--version <x.y.z> 可指定確切版本，而非最新穩定版。之後請執行 godot-cli build。參見擴充套件。
remove-plugin
在 project.godot 的 [editor_plugins] 區段中停用 addon。不會刪除 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，讓 addon 在下次開啟編輯器時載入。沒有 .csproj 的專案會略過。
| 旗標 | 說明 |
|---|---|
--configuration <cfg> | MSBuild 組態。預設為 Debug。 |
--dotnet-path <path> | 使用此 dotnet 執行檔，而非 PATH 上的版本。 |
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：bearer token。預設為 GODOT_MCP_TOKEN。 |
exec
使用 script-execute 工具在專案的編輯器中執行 C#。程式碼是一般的陳述式；最後一個運算式即為結果。若該專案已有編輯器在執行，會重複使用它（你的編輯器必須處於 Custom 模式並已啟動本機伺服器）。否則 exec 會建置專案並啟動連線到本機伺服器的無視窗編輯器，該編輯器在沒有呼叫經過 --idle 秒後結束（預設 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| 旗標 | 說明 |
|---|---|
--path <path> | 專案資料夾。 |
-f, --file <file> | 從檔案讀取程式碼（- 代表 stdin）。 |
--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> | Bearer token。預設為 GODOT_MCP_TOKEN。 |
--raw | 輸出原始的工具回應 JSON。 |
編譯錯誤會指向程式碼片段的該行，並以代碼 1 結束。
login
使用 OAuth 2.1 裝置流程登入 ai-game.dev，並將憑證儲存到 ~/.ai-game-dev/credentials.json，編輯器會自動讀取。請參閱連接 AI 用戶端。
| 旗標 | 說明 |
|---|---|
--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 用戶端。
| 旗標 | 說明 |
|---|---|
--list | 列出所有代理程式 id。 |
--url <url> | 覆寫伺服器主機，例如本機伺服器。 |
--token <token> | 覆寫 token。預設為 GODOT_MCP_TOKEN。 |
--no-pin | 寫入單純的 /mcp URL，而非釘選的 URL。 |
--oauth | 雲端：僅含 URL 的設定；代理程式會以自己的 OAuth 登入。 |
--regenerate-key | 雲端：建立新的專案金鑰並撤銷舊的。 |
setup-skills
godot-cli setup-skills <agent> [path] 會為外掛的各工具系列，將 SKILL.md 檔案寫入代理程式的 skills 資料夾（例如 .claude/skills）。不需要有執行中的編輯器。--list 會顯示各代理程式的 skills 支援情況。
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> | 透過受管理的伺服器執行檔設定 agent（需要 install-plugin --with-server）。 |
--url <url> | 搭配 --agent：覆寫伺服器 URL。 |
run-tool 與 run-system-tool
直接透過伺服器的 HTTP API 呼叫工具：run-tool 會 POST 到 /api/tools/<tool>，run-system-tool 則 POST 到 /api/system-tools/<tool>（對 MCP 用戶端隱藏的工具，例如 ping）。
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 token。預設為 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 應用程式有專屬的
gamedevCLI：App CLI。 - Unity 與 Unreal 分別有
unity-mcp-cli與unreal-mcp-cli：請參閱 Unity MCP 與 Unreal MCP 的 wiki。