godot-mcp-go

<p align="center"> <img src="https://raw.githubusercontent.com/regiellis/godot-mcp-go/main/website/public/brand/mark.svg" width="104" alt="godot-mcp: a terminal prompt in a rounded tile with a live-connection dot"> </p> # 工具列表 [](https://godotengine.org) [](https://go.dev) [](LICENSE)   通过命令行驱动正在运行的 **Godot 4.7+** 编辑器 — 以及 AI 代理 — 来构建场景、编写 GDScript 或 C#、播放和检查游戏，并内省引擎的实时 API。Go CLI 通过 WebSocket 与 GDScript 编辑器插件通信。**312 个命令，涵盖 49 个组**，每个命令都针对实时编辑器进行了验证。 > [!TIP] > **一个表面，两个前门 — 不会让您的代理上下文混乱。** 这既是一个 **CLI**，又是一个 **MCP 服务器**，共用相同的 312 个命令。基于终端的代理可以直接跳过 MCP：CLI 是自描述的（`godot-mcp help all` 列出目录；`godot-mcp <group> <command> --help` 打印真实的参数表），因此 shell 驱动的成本为 **零** 工具模式。对于通过 MCP 加载工具模式的客户端（Claude Code 这样做），仅为他们实际使用的工具付费 — 而 `serve --typed=false` 将表面折叠为一个通用的 `godot_run` 加上只读的 `godot://` 资源，供急切地携带每个模式的客户端使用。 > [!NOTE] > **此仓库是一个单向公共镜像，** 发布为压缩快照 — 它与规范开发仓库没有共享提交历史，因此 **拉取请求无法直接合并**。对于错误、功能请求或更改，请打开一个 [**问题**](https://github.com/regiellis/godot-mcp-go/issues) 或开始一个 [**讨论**](https://github.com/regiellis/godot-mcp-go/discussions)。这就是开发被跟踪的地方。 **`asset-library` 分支** 是 [Godot 资源库](https://godotengine.org/asset-library) 的打包工件（仅限插件的 `addons/` 根快照）— 它永远不会合并到 `main`。 ## 这难道不是 Godot 内置的 CLI 吗？ 不 — 它们做不同的工作，而且它们是组合的。 **Godot 自己的命令行启动一个 Godot 进程；godot-mcp 与已经运行的进程对话。** | | Godot 的 CLI (`godot --headless`, `--export-release`, `--script`) | godot-mcp | | --- | --- | --- | | 进程模型 | 为每个调用启动一个新的引擎进程，每次冷启动 | 通过 WebSocket 连接到您已经打开的编辑器 | | 会话状态 | 无 — 无打开的场景，无选择，无撤销历史 | 实时会话：编辑场景，选择，未保存的工作，UndoRedo（每个突变 Ctrl+Z 安全） | | 编辑 | 对项目文件运行脚本一次 | 针对打开的场景的 312 个命令，具有打开场景的冲突保护 | | 运行中的游戏 | 启动的进程 *是* 游戏；没有什么可以进入其中 | 一个实时通道进入其中：读取状态，`eval`，注入输入，等待信号，截图 | | 内省 | `--doctool` 离线转储文档 | `engine.*` 读取正在运行的构建的 ClassDB，实时 | | 构建目的 | CI — 导出，导入，批处理脚本 | 交互式构建和游戏测试，由终端用户和 AI 代理 | 继续使用 Godot 的 CLI 进行导出和 CI；godot-mcp 本身会调用它来启动编辑器。 ## 它与其他的 Godot MCP 有什么不同？ 有很多 Godot MCP 服务器存在，而且好的服务器都是原生编辑器 — 所以“在编辑器中运行”并不是一个区分因素。 这个服务器是一个 **协开发者**，在多个维度上更深入： - **它驱动正在运行的游戏。** `runtime` 和 `input` 组通过两跳 IPC 检查和控制实时游戏 — 读取正在运行的场景树，设置/读取节点状态，`eval`，捕获帧，`await_signal`，轮询 `runtime.errors`，注入输入以进行确定性游戏测试。 大多数编辑器时间 MCP 服务器在“场景组装完成”后停止；这个服务器构建场景并通过运行它来证明它有效。 - **无法过时的模式。** 默认情况下，`serve` 暴露的每个命令都是一个类型化的 MCP 工具，其模式从插件自己的参数文档中实时构建，因此工具表面永远不会偏离编辑器注册的内容。 `serve --typed=false` 折叠为单个通用的 `godot_run`，适用于工具受限的客户端（竞争对手提供约 40-160 个固定模式）— 加上只读的 `godot://` 资源，用于拉取项目/场景/引擎状态而无需花费一个工具回合。 - **也支持 C# 项目。** `script.create` 编写 C# 模板，`csharp.setup` 搭建 csproj/sln，`csharp.build` / `script.validate` 编译并带有结构化每个文件的诊断信息（需要 Godot .NET 编辑器构建和 dotnet SDK）。 - **内省代替包装器。** 实时 `ClassDB` *是* 功能列表（`engine.search`，通用 `node.set`/`node.get`，`runtime.eval`），因此新引擎功能在您升级后立即可用，无需此工具的新版本。 - **实时编辑器集成** — 命令针对真实的 SceneTree 运行，具有 UndoRedo（Ctrl+Z 安全）和打开场景冲突保护，而不是离线 `.tscn` 重写以避免覆盖未保存的工作。 - **崩溃感知发现** — 每个项目的端口发现带有 `running`/`starting`/`crashed`/`closed` 判决的连接失败，因此代理有意恢复而不是盲目重启。 - **安全防护** — `127.0.0.1` 仅限，审计代码执行，不安全的编辑器 IO 防护，以及每个写入汇集的项目路径监禁。 - **一个工艺层** — 一个代理技能加上 26 个工艺参考（3D 控制器，平台游戏，卡牌构建，交互式音乐，着色器，多人游戏，保存系统...），教导代理如何像 Godot 开发人员一样构建，而不是仅仅调用工具。 没有其他服务器提供此功能。 具体来说，与最流行的编辑器原生服务器 ([`hi-godot/godot-ai`](https://github.com/hi-godot/godot-ai)) 相比： | | godot-ai | godot-mcp-go | | --- | --- | --- | | 编辑器集成 | 实时 | 实时 | | 运行游戏控制 | 无（仅限编辑器） | 完整的 `runtime` + `input` 组 | | MCP 工具模式 | 约 43 个固定 | 每个命令类型化，实时构建 — 或仅限 1 个 (`godot_run`) + `godot://` 资源 | | 表面 | 约 120 个操作 | 312 个命令 / 49 个组 | | 运行时依赖 | Python + `uv` | 单个 Go 二进制文件 | | 工艺层 | 工具参考 | 26 个工艺文档 + 技能 | | 分发 | 资源库，一键安装，多客户端自动配置，大社区 | CLI `install`/`create`/`configure`，自行托管 | 诚实的取舍：godot-ai 今天拥有更大的社区和资源库的一键访问。 这个项目的优势在于深度 — 驱动运行中的游戏，实时内省和工艺层 — 及其独特的表面：`spatial`，`pcg`，`wfc`，`scatter`，`skeleton` 和 `authoring` 组在其他地方都没有对应，而其中大部分工具表面映射到这里的通用命令。 ## 它是如何工作的 ``` godot-mcp（Go CLI / 客户端） ──WebSocket(JSON-RPC 2.0):9080──▶ Godot 编辑器插件（服务器） │ 文件 IPC（user://） ◀──────┘──▶ 运行中的游戏 （MCPGameInspector / MCPGameInput 自加载） ``` - **插件在编辑器内运行 WebSocket 服务器**（长期运行的进程）。 CLI 是一个短寿命的客户端，它对接，运行一个命令，然后退出。 - CLI **从 `<project>/.godot/godot-mcp.json` （由插件写入）自动发现端口**，在项目内运行时；否则传递 `--port` （默认 `9080`）。 - **`runtime`/`input` 命令通过文件 IPC 访问正在运行的游戏**，由游戏端的两个 autoloads 代理 — 或对于无编辑器 **调试构建**，通过游戏自己的直接服务器 (`godot-mcp --game …`，项目设置中的选择加入） — 因此您可以检查实时场景树，读取/设置节点状态，捕获帧，并模拟输入。 - 每个编辑器突变都经过 Godot 的 **UndoRedo** （Ctrl+Z 安全）。 ## 需求 - **Godot 4.7+** （使用 `godot` 启动）。 - **Go 1.26+** 构建 CLI。 - [Task](https://taskfile.dev) （可选但推荐）用于开发工作流。 > [!IMPORTANT] > **仅限 Godot 4.7+**。此版本仅针对 Godot 4.7 及更新版本构建和测试。 早期版本（4.6 及以下，以及 3.x 系列）**不支持**，且不期望其工作 — 插件针对 4.7 API。 > [!NOTE] > **C# / .NET？** 支持。 `csharp` 组搭建并构建 .NET 项目（`csharp.info` / `csharp.setup` / `csharp.build`），而 `script.*` 是 C# 感知的：`script.create` 编写 C# 类模板，`script.validate --path X.cs` 编译并带有每个文件的结构化诊断信息，`script.list` 识别 C# 类。 *运行* C# 脚本在编辑器中需要 Godot **.NET 编辑器构建** 加上 dotnet SDK（`godot-mcp doctor` 会检查它）；`editor.run_script` / `runtime.eval` 执行 GDScript 两种方式，而内省层与语言无关。 > **Windows 注意：** 如果编辑器曾经崩溃并出现 `ERROR: WASAPI: GetBufferSize` 错误，则另一个应用程序已获得 **独家** 控制权，访问您的音频设备（Chrome 恢复时是一个常见的罪魁祸首）。 在 Windows 音量设置中关闭独家模式（设备属性 → 高级 → 取消选中“允许应用程序独家控制”）。 这是一个操作系统/音频问题，而不是此插件的问题。 (`--audio-driver Dummy` 也会规避它，如果需要。) ## 构建 ```sh task build # -> bin/godot-mcp(.exe) # 或： go build -o bin/godot-mcp ./cmd/godot-mcp ``` ## 安装到项目 从解压的发布包中，使用以下命令将插件（和代理技能）安装到任何 Godot 项目中： ```sh godot-mcp install --project /path/to/your/project --enable ``` 从零开始？使用以下命令引导一个全新的 Godot 4.7 项目，并将插件配置好： ```sh godot-mcp create --path ./mygame --install --enable ``` 复制 `addons/godot_mcp/` 和 `.claude/skills/godot-mcp/` 并在 `project.godot` 中启用插件。 有关标志和手动替代，请参阅 [INSTALL.md](INSTALL.md)。 ## 快速开始 1. 在 Godot 4.7+ 中打开测试项目（或您自己的项目，已安装插件）： ```sh task editor # godot --path project --editor ``` 确保 **Godot MCP** 插件已启用（项目 → 项目设置 → 插件）。 插件打印 `[MCP] 服务器监听 ws://127.0.0.1:9080`。 2. 在项目目录内驱动它： ```sh godot-mcp project info godot-mcp scene tree godot-mcp node add --type Sprite2D --name Player --parent-path . godot-mcp node set --node-path Player --property position --value "Vector2(100, 200)" ``` ### 发现，然后驱动 由于 CLI 与 **实时** 引擎对话，您可以询问它您的引擎构建实际支持什么，而不是猜测： ```sh godot-mcp engine search --query offset_transform # 查找所有类中的成员 godot-mcp engine class-info --class Control --filter transform ``` 即使没有类型化的包装器，`node.set`/`node.get` 适用于任何属性实时节点公开的属性，而 `editor.run_script` / `runtime.eval` 运行任意的 GDScript — 因此无论其版本如何，都可以访问正在运行的引擎的整个 API。 ### 游戏测试循环 ```sh godot-mcp scene play --mode main godot-mcp runtime tree godot-mcp input action --action ui_accept --pressed true godot-mcp runtime get --node-path Player --properties '["position"]' godot-mcp runtime screenshot --save-path user://shot.png godot-mcp scene stop ``` ## 用作 MCP 服务器 `godot-mcp serve` 作为 [模型上下文协议](https://modelcontextprotocol.io) 服务器通过 stdio 运行，因此 MCP 客户端（Claude Desktop，Claude Code，...）可以直接驱动 Godot。 默认情况下，每个命令都是一个 **类型化的 MCP 工具**，具有从插件自己的参数文档中实时构建的真实模式；`godot_run` 保留为通用逃生门（`{ "method": "<group>.<command>", "params": {...} }` — 与 CLI 相同的表面），`serve --typed=false` 将工具受限的客户端保留在单个工具上。 `godot_run` 和类型化的 `runtime_*`/`input_*` 工具接受 `game: true` 以驱动一个独立的调试构建游戏 **无需打开编辑器**。 模型通过 `engine.search`/`engine.class_info` 发现正在运行的引擎的 API，然后执行。 客户端配置示例： ```json { "mcpServers": { "godot-mcp": { "command": "godot-mcp", "args": ["serve", "--project", "/path/to/your/project"] } } } ``` Godot 编辑器必须打开并启用插件（与 CLI 一样）。 `--project` 设置服务器在那里发现插件端口。 ## 实时仪表盘（可选） `godot-mcp dashboard` 启动一个小型 Web UI，显示实时活动 — 工具调用、错误率、按组分解、活动连接、正常运行时间和最近活动提要 — **所有** 流经插件的内容（CLI，`serve`/MCP，任何客户端）。 页面（htmx + anime.js）及其资产嵌入二进制文件；不需要 Node/构建步骤。 ```sh godot-mcp dashboard --port 8090 # 然后打开 http://127.0.0.1:8090 ``` 从项目目录内运行它（它像 CLI 一样发现插件端口），或传递 `--project DIR` / `--addon-port N`。 它保持单个持久连接并轮询插件的 `stats.snapshot`。 ## 在此基础上构建 CLI 是一个自动化表面，而不仅仅是键盘。 合同：stdout 上的结果为 JSON（或 `--format tsv` 用于 shell 工具），stderr 上的错误带有 JSON-RPC 代码，退出代码 `0`/`1`/`2`，从项目目录发现端口，以及 `doctor`/`status` 作为可脚本化的预飞行检查。 目录本身是可查询的 JSON — `engine commands --docs` 返回每个命令带有类型化参数 — 因此生成器和 UI 从不硬编码命令列表。 在它下面是稳定的 JSON-RPC-over-WebSocket 线缆，任何东西都可以说：Python 脚本，浏览器面板，驱动独立游戏的 QA 夹具 `--game`。 ```bash # 隐藏编辑场景中的所有 Label godot-mcp batch find-nodes-by-type --type Label | jq -r '.matches[].path' \ | while read -r p; do godot-mcp node set --node-path "$p" --property visible --value false; done ``` 工作示例 — CI 烟雾测试，Python 客户端，工作浏览器面板： [Scripting and CI](https://regiellis.github.io/godot-mcp-go/docs/automation/) · [您自己的工具和 UI](https://regiellis.github.io/godot-mcp-go/docs/building-on-top/). ## 命令组 `analysis` `android` `anim_tree` `animation` `audio` `authoring` `batch` `camera` `cleanup` `csg` `csharp` `doc` `editor` `engine` `export` `fs` `gridmap` `import` `input` `input_map` `lighting` `localization` `material` `mesh` `multiplayer` `navigation` `pcg` `physics` `profiling` `project` `resource` `runtime` `scatter` `scene` `scene2d` `scene3d` `script` `shader` `skeleton` `spatial` `test` `theme` `tilemap` `ui` `wfc` 调用方式为 `godot-mcp <group> <command> [--flag value ...]`。名称接受 kebab- 或 snake-case；值以 `[`/`{` 开头的值被解析为 JSON。出错时 CLI 在 stderr 上打印 JSON-RPC 代码、消息和任何建议。 从 CLI 本身探索目录：`godot-mcp help all` 列出每个组的命令，`godot-mcp <group> --help` 缩小到一个组，`godot-mcp <group> <command> --help` 打印该命令的参数表。 ## 代理技能 `skills/godot-mcp/SKILL.md` 是一个 Claude Code 技能，教导代理有效使用 CLI：发现-驱动循环，Godot 的节点/场景组成风格，命令组，核心工作流程和陷阱。将其放入项目的 `.claude/skills/` 目录中，为 AI 代理提供完整的上下文。 ## 布局 ``` cmd/godot-mcp/ Go CLI 入口 internal/{protocol,client}/ JSON-RPC 信封 + WebSocket 客户端/发现 project/ Godot 4.7 测试项目（运行 godot） project/addons/godot_mcp/ GDScript 插件（commands/, services/, utils/） skills/godot-mcp/SKILL.md 代理技能 Taskfile.yml 开发任务（运行 task 列表） ``` 命令实现位于 `project/addons/godot_mcp/commands/`（每个组一个 `*_commands.gd`），在 `command_router.gd` 中注册；添加一个命令，请在那里注册一个处理程序。`services/` autoloads 代理运行游戏的 IPC。 ## 许可证 MIT - 参见 [LICENSE](LICENSE)。