godot-cli 参考
Godot MCP 的 godot-cli 全部命令与参数，涵盖 install-plugin、login、setup-mcp、open、exec、run-tool、configure 和 install-extension。
godot-cli 是 Godot MCP 的命令行工具，已发布在 npm 上。它会安装插件、让你登录、写入 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] | 安装插件、修补 .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 下载插件发布版（或复制本地版本），将 NuGet PackageReference 和扩展目录 <EmbeddedResource> 添加到 .csproj，设置 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 读取注册码，使其不会留在 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] 段中禁用插件。它不会删除 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> | 使用此 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] 写入该 agent 的 MCP 配置，默认固定到此项目。agent id 与配置文件列在连接 AI 客户端中。
| 参数 | 说明 |
|---|---|
--list | 列出所有 agent id。 |
--url <url> | 服务器主机覆盖，例如本地服务器。 |
--token <token> | Token 覆盖。默认 GODOT_MCP_TOKEN。 |
--no-pin | 写入普通的 /mcp URL，而非固定到此项目的 URL。 |
--oauth | 云端：仅配置 URL；agent 使用自己的 OAuth 登录。 |
--regenerate-key | 云端：创建新的项目密钥并吊销旧密钥。 |
setup-skills
godot-cli setup-skills <agent> [path] 将插件各工具族的 SKILL.md 文件写入该 agent 的 skills 文件夹（例如 .claude/skills）。它不需要运行中的编辑器。--list 显示每个 agent 的 skills 支持情况。
configure
在 .godot-mcp/features.json 中列出或更改 MCP 客户端可见的工具、提示和资源。隐藏的条目在按名称调用时仍会运行。
| 参数 | 说明 |
|---|---|
--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 向 /api/tools/<tool> 发送 POST 请求，run-system-tool 向 /api/system-tools/<tool> 发送 POST 请求（后者用于对 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。