godot-mcp-bridge

<div align="center"> <img src="./icon.png" width="96" alt="godot-mcp-bridge" /> # godot-mcp-bridge **与你共同工作的AI，在Godot编辑器中与你协同工作——而不是取代你。** [](./LICENSE) [](https://godotengine.org) [](#-what-can-it-do) [](https://github.com/TomasLucasUTN/godot-mcp-bridge/commits/main) [](https://github.com/TomasLucasUTN/godot-mcp-bridge/stargazers) </div> 每个Godot MCP服务器都让AI驱动编辑器。**这个服务器还告诉AI你刚刚做了什么**——你打开的场景，你选中的节点，你保存的文件——这样你们可以在同一时间共同合作在一个项目上而不会相互干扰。添加一个真正的逐步调试器，通过Godot的语言服务器进行作用域感知重构，实时树编辑而不会覆盖你的未保存工作，以及211个工具，每个工具都针对正在运行的编辑器进行了验证，而不是仅仅编写。 从[tomyud1/godot-mcp](https://github.com/tomyud1/godot-mcp)（MIT许可）开始，目前已经有显著的不同——参见[`CHANGELOG.md`](./CHANGELOG.md)。 --- ## 💬 你会对它说什么 > *"玩家有时会穿过地板。在 `_physics_process` 中设置断点，并告诉我发生时 `velocity` 是多少。"* > *"为我创建一个敌人：CharacterBody2D，圆形碰撞器，精灵，巡逻脚本，并将其放入 `enemies` 组中。"* > *"运行游戏，按跳跃键，截图，并告诉我动画是否播放。"* > *"哪些资源不再被任何人引用？"* > *"导出一个Windows调试构建，并告诉我何时完成。"* 在底层，这是一个从暂停帧中读取的断点命中，一个脚手架场景树，一个运行时输入 + 截图循环，一个依赖扫描，以及一个异步无头构建——但你不需要知道哪个工具执行哪个任务。 <details> <summary>调试会话实际返回的内容</summary> ```jsonc // debug_launch({scene: "res://scenes/level.tscn"}) { "state": "stopped", "stopped_reason": "breakpoint", "hit_breakpoint": true } // debug_stack_trace() { "frames": [{ "name": "_physics_process", "line": 17, "source": ".../scenes/player.gd" }] } // debug_variables({variables_reference: 1}) ← Locals 范围 { "variables": [{ "name": "delta", "value": "0.01666666666667" }, { "name": "direction", "value": "<null>" }] } // debug_evaluate({expression: "velocity"}) { "result": "(0.0, 0.0)" } ``` 真实输出来自测试项目——`delta` 正好是 1/60，匹配其 60 Hz 物理 tick。 </details> --- ## ✨ 为什么选择这个 **它是双向的。** AI 可以轮询 `get_editor_activity` 以查看你刚刚在编辑器中做了什么——选择，场景打开/关闭/保存，脚本焦点，资源保存，资产重新导入，撤销/重做，你所在的屏幕——用标签标记人类操作与其自身操作。它可以发现你移动了某些东西而无需询问。其他Godot MCP都是单向的：AI驱动，并且对你盲目。（通过在2026年7月阅读12个竞争服务器的源代码进行检查，而不是他们的README。） **它不会覆盖你的工作。** 许多Godot MCP服务器编辑你的 `.tscn` 文件到磁盘上。如果你在场景中有未保存的更改，它们会悄悄覆盖它。这里，当场景打开时，每个变异工具都会编辑 **实时编辑器树** 而不是——你的未保存编辑得以保留，每个更改都通过Godot的 **撤销系统** （Ctrl+Z 有效）。关闭的场景仍然像往常一样编辑到磁盘上。 **声明经过测试，而不是断言。** 每个工具都已针对真实的Godot 4.7运行 - 204 由人工驱动编辑器（2026年7月的完整185工具通行证，以及调试器和语言服务器工具端到端添加），以及无头GDScript套件中的15个断言覆盖多人游戏脚手架。该工作发现并修复了四个真实的错误：碰撞预设静默保存空位掩码，实时场景写入在报告失败后留下部分状态，始终返回空的2D导航网格烘焙，以及导出轮询直到超时。参见[限制](#-limitations)了解它仍然无法执行的操作。 更多它所做的事情： - **逐步调试器** - 设置断点，逐步执行，读取真实的调用堆栈和帧变量，在暂停的帧中评估表达式，通过Godot自己的调试适配器。停止在故障处并查看实际值，而不是从 `print()` 输出中推断。 - **真实的无头导出** - 通过影子工作空间克隆构建实际的游戏二进制文件，异步执行，不会冻结编辑器（`export_project` → `get_export_status`）。 - **运行您的真实测试** - `run_gut_tests` 执行您的GUT单元套件（同步或异步）并报告通过/失败，以便AI根据真实结果而不是猜测采取行动。 - **驱动正在运行的游戏** - 调用方法，设置属性，`await`信号，`game_eval`代码片段，记录/重放输入，快照实时树，甚至是多人游戏对等节点生成框架（`spawn_headless_peers`）- 确定性播放测试，无需截图。 - **沙盒路径** - 每个路径都受到遍历项目目录的保护（CVE-2026-15522中另一个服务器的错误类别）。 - **为您编写样板** - `wire_signal`连接信号 **和** 生成正确类型的处理程序；`generate_onready_refs`为子树发出类型化的`@onready`变量；`scaffold_entity`在一个调用中构建角色（身体+碰撞形状资源+精灵+运动脚本）；`scaffold_state_machine`布局一个工作的FSM。物理层可以按 **名称** 而不是位索引设置。 - **告诉你什么正在腐烂** - `find_unused_resources`，`detect_circular_dependencies`，`analyze_scene_complexity`和`analyze_signal_flow`（捕获处理程序不存在的连接-只有在运行时才会出现的错误）。 - **视觉回归** - `compare_screenshots`差异两个帧并报告更改的百分比和区域，因此“我的更改是否实际更改了屏幕？”有了答案。 - **像人类一样测试您的UI** - 按可见的标题点击按钮（`click_control_runtime({text: "Start"})`，如果文本不明确，则拒绝并列出候选项），然后使用`assert_screen_text`断言屏幕上的内容-读取实时控制树，因此它在无OCR的情况下无头工作。 - **不半工作的本地化** - `sync_localization`注册Godot从您的CSV生成的 `.translation` 文件（手动步骤，使语言永远不会加载），并报告您尚未翻译的每个密钥，按本地化。 - **自我解释的设置** - `npx godot-mcp-bridge install`安装并启用插件，`doctor`诊断损坏的设置；`diagnose_connection`告诉AI编辑器为何无法连接。 - **快速 + 健壮** - `batch_execute` / `batch_scene_edit`将N个调用削减为1；重读（`read_scene`，`scene_tree_dump`，`classdb_query`）采用`max_depth` / `filter`保持令牌便宜；默认情况下只有35个工具加载，以便代理保持专注。 - **符号准确的重构** - `gd_rename`和`gd_references`通过Godot的语言服务器，因此它们理解作用域：重命名本地`speed`不会像文本搜索那样影响无关类的`speed`。`gd_diagnostics`在不运行游戏的情况下显示类型错误。 - **多人游戏脚手架** - `mp_add_spawner` / `mp_add_synchronizer`构建Godot 4的复制节点（包括使它们繁琐的`SceneReplicationConfig`子资源），`mp_wire_rpc`编写正确注释的`@rpc`方法，`mp_scaffold_lobby`生成主机/加入管道。 - **C#，诚实** - `create_csharp_script`搭建样板，`csharp_status`直接告诉你C#是否可以在此处工作。标准Godot构建没有C#支持：`.cs`文件保存良好，附加到无处，并静默失败。最好在编写任何代码之前发现这一点。 - **选择确认门** - 设置`GODOT_MCP_REQUIRE_CONFIRM=true`和具有无撤销路径的操作（文件删除/重命名，脚本重写，大规模重命名，项目设置）需要明确的`confirm: true`。对**打开**场景的编辑除外-这些落在Godot的撤销历史中，因此Ctrl+Z（或`undo_last`）已经涵盖了它们。 - **飞行前验证** - `validate_scripts`扫描每个`.gd`；`validate_scene_integrity`标志节点剩余空所需资源；`validate_meshes`捕获空几何。 --- ## ⚙️ 运行多个项目 一台机器上的一个项目无需配置。如果你运行多个项目 - 或者在CI编辑器旁边运行自己的项目 - 请设置两项，因为插件拨打固定端口并且无法分辨哪个服务器回答： | 变量 | 位置 | 它执行的操作 | |---|---|---| | `GODOT_MCP_PORT` | 服务器 **和** 编辑器 | 桥梁的端口。给每个项目一个。 | | `godot_mcp/network/port` | 项目设置 | 按项目端口，如果您不想在编辑器上设置环境变量。`GODOT_MCP_PORT`覆盖它。 | | `GODOT_MCP_PROJECT` | 服务器 | 此服务器服务的项目的绝对路径。具有不同项目打开的任何编辑器都会被拒绝。 | `GODOT_MCP_PROJECT` 是即使只有一个项目也值得设置的变量。没有它，第一个到达端口的编辑器被信任执行每个工具调用，因此一个无关的编辑器可能会意外地接收到为另一个项目编辑而发出的编辑。设置后，该连接将被拒绝，编辑器会告知而不是静默地进行操作。 --- ## 📊 比较 在2026年7月通过阅读每个项目的**源代码**进行检查，而不是其营销。星级计数主要跟踪项目发布的时间，因此它被列在最后而不是第一。 | | **godot-mcp-bridge** （此仓库） | [yurineko73/Godot-MCP-Native](https://github.com/yurineko73/Godot-MCP-Native) （最活跃） | [tomyud1/godot-mcp](https://github.com/tomyud1/godot-mcp) （分支源） | [Coding-Solo/godot-mcp](https://github.com/Coding-Solo/godot-mcp) （最多星） | |---|---|---|---|---| | 工具 | 211（默认35个） | 155 | 42 | ~14 | | 实时树编辑 + 撤销 | ✅ | ✅ | ❌ （覆盖磁盘上的打开场景） | ❌ | | 逐步调试器 | ✅ | ✅ | ❌ | ❌ | | 驱动运行中的游戏（输入，`game_eval`） | ✅ | ✅ | ❌ | ❌ | | **看到你刚刚做了什么** （`get_editor_activity`） | ✅ | ❌ | ❌ | ❌ | | 异步无头导出（不会阻塞编辑器） | ✅ | CLI导出 | ❌ | ❌ | | 运行您的真实测试套件（GUT） | ✅ | ❌ | ❌ | ❌ | | 上次发布 | 活跃 | 活跃 | 2026年4月 | 2026年4月 | | GitHub星级 | — | 464 | 397 | 4.9k | 诚实的阅读：撤销，调试器和运行时控制现在是基本要求——好的项目都有这些。没有人做的就是双向的那一部分，而最受欢迎的两个选项自四月份以来就没有发布过。 --- ## 📦 快速入门 ### 0. 安装Node.js（一次性设置） 从 **[nodejs.org](https://nodejs.org/en/download)** 下载并运行安装程序（LTS版本）。这是一个标准的安装程序——不需要终端。 ### 1. 安装Godot插件 **一条命令，从你的Godot项目文件夹内部：** ```bash npx godot-mcp-bridge install ``` 该命令会将插件复制到 `addons/godot_mcp/` 并在 `project.godot` 中启用插件（首先备份文件，并保留其他插件和设置完整）。添加 `--client claude-desktop` 或 `--client cursor`，它还会在该客户端的配置中注册服务器。 某些东西无法连接？运行此命令，它会告诉您哪一步出了问题： ```bash npx godot-mcp-bridge doctor ``` <details> <summary>如果您想手动操作</summary> 将此仓库中的 `addons/godot_mcp/` 文件夹复制到您的Godot项目目录的 `addons/` 目录中。然后进入 **项目 → 项目设置 → 插件** 并启用 **Godot MCP** 插件。 （来自上游项目的“Godot AI Assistant tools MCP”AssetLib列表属于原始的fork项目，而不是这个 - 从那里安装会得到上游插件，而不是这个fork。） </details> ### 2. 将服务器配置添加到您的AI客户端 **Claude Desktop** - 设置 → 开发者 → 编辑配置 → 打开配置文件并粘贴： Mac / Linux： ```json { "mcpServers": { "godot": { "command": "npx", "args": ["-y", "godot-mcp-bridge"] } } } ``` Windows： ```json { "mcpServers": { "godot": { "command": "cmd", "args": ["/c", "npx", "-y", "godot-mcp-bridge"] } } } ``` **Cursor** - 设置 → MCP → 添加服务器： Mac / Linux： ```json { "mcpServers": { "godot": { "command": "npx", "args": ["-y", "godot-mcp-bridge"] } } } ``` Windows： ```json { "mcpServers": { "godot": { "command": "cmd", "args": ["/c", "npx", "-y", "godot-mcp-bridge"] } } } ``` **Claude Code** - 在终端中运行： ```bash claude mcp add godot -- npx -y godot-mcp-bridge ``` 适用于任何MCP兼容的客户端（Cline，Windsurf等） ### 3. 重启您的AI客户端 关闭并重新打开Claude Desktop / Cursor /您的客户端，以便它获取新的配置。 ### 4. 重启您的Godot项目 点击Godot编辑器中的 **重启项目**。在右上角查看 - 您应该会看到绿色显示 **MCP 已连接**。您可以开始了。 --- ## 🧰 它能做什么？ ### 211个工具，默认35个 一个很大的总是开启的工具列表会让AI代理在不相关的功能之间游移，并浪费上下文在它永远不会使用的定义上。所以只有 **`核心`**（35个工具）默认可见 - 这是最小的集合，可以在整个会话中正常进行：查看周围，编辑场景和脚本，运行游戏，读取错误。 所有其他工具都按 **意图** 分组，只需一个调用即可访问： `enable_toolset({ name: "runtime" })`。`list_toolsets` 显示每个集合、它的用途和内部的工具名称 - 以便AI可以在不首先加载整个目录的情况下找到它需要的内容。没有任何东西是无法访问的。 有关目标到工具的索引和每个主题的使用指南，请参阅 [`docs/TOOLS.md`](./docs/TOOLS.md) - 服务器通过 `get_guide` 工具以可浏览的形式公开相同的内容。 | 工具集 | 工具 | 用途 | |---------|-------|---------| | **核心** *(始终开启)* | 35 | 查看周围（`read_scene`，`scene_tree_dump`，`search_project`，`classdb_query`），编辑场景/节点（实时树 + 撤销，`batch_scene_edit`），脚本，运行游戏，读取错误 | | **运行时** | 25 | 驱动正在运行的游戏：输入（键盘/鼠标/**游戏手柄/触摸**），`game_eval`，实时节点/属性访问，`await_signal_runtime`，基于文本的UI点击 + `assert_screen_text`，输入记录/重放，多人游戏 + `spawn_headless_peers` | | **调试** | 11 | 通过Godot自己的调试适配器的逐步调试器：断点，逐步执行，调用堆栈，作用域变量，暂停帧中的表达式求值 | | **代码智能** | 8 | Godot的语言服务器：作用域感知 `gd_definition`，`gd_references` 和 `gd_rename`（不同于文本搜索），以及在不运行游戏的情况下进行类型诊断 | | **场景编辑** | 14 | 更深入的场景工作：碰撞形状，精灵/网格/材质，组，锚点，空间查询 | | **项目配置** | 13 | 项目设置，输入映射，自动加载，资源，`sync_localization` | | **动画** | 12 | AnimationPlayer关键帧/ AnimationTree状态机 | | **编辑器** | 11 | 编辑器本身：`get_editor_activity`（你刚刚做了什么），选择，场景选项卡，性能 | | **物理** | 7 | 碰撞形状，射线投射，**按名称**的图层，碰撞预设 | | **图块地图** | 8 | TileMapLayer单元格绘制，地形 + 确定性按位自动拼接 | | **分析** | 6 | `find_unused_resources`，`detect_circular_dependencies`，`analyze_scene_complexity`，`analyze_signal_flow`，`get_project_statistics`，`compare_screenshots` | | **脚手架** | 11 | `wire_signal`，`generate_onready_refs`，`scaffold_entity`，`scaffold_state_machine`，`create_csharp_script`，再加上多人游戏：`mp_add_spawner`，`mp_add_synchronizer`，`mp_wire_rpc`，`mp_scaffold_lobby` | | **测试** | 6 | GUT测试运行器（同步/异步），场景/网格完整性验证，断言 | | **UI** | 6 | 主题资源，颜色，样式框覆盖 | | **3D** | 6 | 网格实例，照明预设，材质，环境，相机，网格图 | | **着色器** | 6 | 创建/读取/编辑GDShader，分配材质，设置参数 | | **导航** | 5 | 导航区域设置，网格烘焙，代理，图层 | | **VFX** | 5 | GPUParticles2D/3D，渐变，预设 | | **重构** | 5 | 项目范围的符号重命名，批量属性编辑，文件移动 | | **导出** | 4 | 导出预设和异步导出作业 | | **音频** | 3 | AudioStreamPlayer变体，公交车 | | **实用工具** | 2 | 2D资产生成，项目/场景可视化 | ### 交互式可视化 运行 `map_project` 并在 `localhost:6510` 获取基于浏览器的资源管理器： - 所有脚本及其关系的强制有向图 - 点击任何脚本以查看变量、函数、信号和连接 - 在可视化中直接编辑代码 - 更改实时同步到Godot - 带有节点属性编辑的场景视图 - 查找重构前的使用情况  --- ## 🏗️ 架构 ``` ┌─────────────┐ MCP（stdio） ┌──────────────┐ WebSocket ┌──────────────┐ │ AI 客户端 │◄────────────────►│ MCP 服务器 │◄─────────────►│ Godot 编辑器 │ │ （Claude， │ │ （Node.js） │ 端口 6505 │ （插件） │ │ 光标） │ │ │ │ │ └─────────────┘ │ 可视化器 │ │ 211 个工具 │ │ HTTP :6510 │ │ 处理程序 │ └──────┬───────┘ └──────────────┘ │ ┌──────▼───────┐ │ 浏览器 │ │ 可视化器 │ └──────────────┘ ``` --- ## ⚠️ 限制 - **仅限本地** - 运行在本地主机上，无远程连接 - **单一连接** - 每次一个Godot实例 - **打开场景的撤销功能涵盖每个编辑** - 节点，属性，资源，动画轨道，图块地图单元格：所有这些都注册在Godot的撤销历史中，代理可以通过 `undo_last` 撤销自己的更改。`batch_scene_edit` 是一个条目，因此Ctrl+Z恢复整个批次。限制值得注意：编辑 **未打开** 的场景会直接写入磁盘，没有撤销条目 - 在那里使用版本控制。一些破坏性工具也支持 `dry_run: true` 以便先预览。 - **AI仍然在Godot知识方面有限** - 它难以理解复杂的UI布局，复合场景和一些节点属性操作；它无法独自创建100％的游戏，但可以帮助调试，编写脚本并陪同您完成旅程。仍在积极开发中 - 欢迎反馈。 --- ## 🔧 开发 要从源代码构建而不是使用npm： ```bash cd mcp-server npm install npm run build ``` 然后将您的AI客户端指向 `mcp-server/dist/index.js` 而不是使用 `npx`。 --- ## 📖 发行说明 每个版本的叙述性写作都存放在 [`release-notes/`](./release-notes/) 中 - 最新的是 [v1.1.0](./release-notes/v1.1.0.md)。有关完整的变更历史，请参见 [`CHANGELOG.md`](./CHANGELOG.md)。 --- ## 🤝 贡献 参见 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。安全问题：请参见 [`SECURITY.md`](./SECURITY.md) 而不是公开问题。 --- ## 📄 许可证 MIT --- **[报告问题](https://github.com/TomasLucasUTN/godot-mcp-bridge/issues)**