godot-mcp-toolkit

<!-- 品牌横幅，1280×640，委托艺术；出处在 docs/media/README.md 中。相对路径，以便在 github.com 上解析；此 README 不在 AssetLib 存档中，无论如何，.gitattributes 导出忽略每个路径在 addons/ 之外。 -->  # Godot MCP 工具包 [](https://github.com/NPGameDev/godot-mcp-toolkit/actions/workflows/ci.yml)  [](LICENSE) 通过 [模型上下文协议](https://modelcontextprotocol.io) 实现 AI 辅助的 Godot 开发。此插件将 Godot 4.2+ 编辑器转变为 MCP 服务器。您的 AI 编码助手可以创建场景、编辑脚本、检查节点、运行游戏测试并读取结果，所有操作都在编辑器中实时进行，而无需离开您的机器。配套的 npm 包 [`@npgamedev/godot-mcp-server`](https://github.com/NPGameDev/godot-mcp-server) 是您的助手与之通信的桥梁。 > 完全在本地运行。无遥测、无云服务、无账户。没有任何数据离开您的机器。 > > 这是一个独立的社区项目，与 Godot 基金会或 Anthropic 无关。 > > 仅限桌面端：Windows、macOS 和 Linux。桥梁需要 Node.js 22 或更新版本。 <details> <summary>不熟悉 MCP？</summary> [模型上下文协议](https://modelcontextprotocol.io) 是一个开放标准，允许 AI 助手使用外部工具。MCP 服务器描述其功能（创建节点、读取脚本、运行游戏），而任何 MCP 兼容的助手（Claude Code、Claude Desktop、Cursor 等）都可以调用这些工具。此插件将您的 Godot 编辑器转变为其中一个工具提供者，而配套的 npm 服务器是您的助手与之通信的桥梁。 </details> > 📐 **[架构 →](docs/architecture/README.md)** 涵盖了工具包的构建方式：其子系统、编辑器/运行时分离以及传输和契约表面。在 [npgamedev.github.io/godot-mcp-toolkit/architecture](https://npgamedev.github.io/godot-mcp-toolkit/architecture) 上也有渲染。 ## 为什么选择这个？ * 构建以适应您的工作流程，而不是相反。* 最能说明问题的数据是 **150+ 操作**。这是工具包实际执行的工作：创建节点、绘制 tilemap 单元格、键入动画轨道、读取实时节点等，共有 150 多个操作。这些操作被打包成 **多达 112 个工具**（始终开启的核心工具 + 28 个按需组），因为工具是客户端工具预算中的一个槽位，而操作是实际可以执行的操作。相关的操作位于一个工具后面，这使得列表保持简短，而操作计数则说明了实际的广度。某些操作是版本受限的，因此较旧的 Godot 版本（降至 4.2）会暴露较少的操作。“多达”是一个字面意思。 两个因素驱动设计，并且它们具有同等的重要性： - **您可以扩展它，而没有固定的上限。** 扩展 API 允许您在 GDScript 中注册自己的工具。它们可以热加载，并像内置工具一样显示给代理，并且对您可以添加的工具数量没有固定的上限。限制是当前系统支持的范围，每个迭代都会提高上限并为扩展提供更多空间。C#/.NET 项目也可以通过相同的方式扩展，这是它适合每个项目而非插件的证明。启发式或第三方依赖的工具故意不属于核心部分，而是在扩展 API 中。 - **您可以检查结果。** 代理的上下文窗口是一个预算，因此工具界面从小开始（~8,800 个代币），只有在代理请求更多时才会增长。下面证据部分介绍了 CI 在每次构建中声明的内容、测试清单涵盖的内容以及何时进行测量。链接，而不是形容词。 主要与 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 一起测试，并兼容任何 MCP 客户端。 ## 快速开始 ### 1. 安装插件 - **Godot AssetLib：** 在编辑器中打开 AssetLib 标签，搜索“Godot MCP 工具包”，下载并安装。 - **手动：** 从 [GitHub Releases](https://github.com/NPGameDev/godot-mcp-toolkit/releases) 下载，解压到项目的 `addons/` 目录中。 ### 2. 启用它 项目设置 → 插件 → **Godot MCP 工具包** → 勾选 **激活**。 您应该看到：MCP 码头出现在底部面板中，输出日志打印 ``` [MCPServer] listening on 127.0.0.1:6550 ``` （端口可能会在 6550 至 6560 之间的任意值；码头的状态部分会命名活动端口）。该行是插件自己的 WebSocket 服务器，位于编辑器内部。npm 桥是一个单独的进程，您的 MCP 客户端稍后会启动，然后拨打此端口。 ### 3. 编写客户端配置 让插件写入它：**项目 → 工具 → MCP 工具包 → 编写 .mcp.json**。 配置文件通过 `npx -y @npgamedev/godot-mcp-server` 运行桥梁，该桥梁在首次连接时获取，因此没有安装步骤。（需要 Node.js 22 或更新版本。运行 `node --version` 检查。）如果您想保持机器上的固定副本，`npm install -g @npgamedev/godot-mcp-server` 也有效。 您应该看到：`.mcp.json` 在项目根目录下，码头的 `.mcp.json` 部分显示它健康。 <details> <summary>更喜欢手动编写 .mcp.json？</summary> ```json { "mcpServers": { "godot-mcp-toolkit": { "command": "npx", "args": ["-y", "@npgamedev/godot-mcp-server"] } } } ``` 在 Windows 上，`npx` 是一个 `.cmd` 伪影，因此请包装它： ```json { "mcpServers": { "godot-mcp-toolkit": { "command": "cmd", "args": ["/c", "npx", "-y", "@npgamedev/godot-mcp-server"] } } } ``` </details> <details> <summary>更喜欢让代理设置它？</summary> 将以下内容粘贴到 Claude Code 中，从您的项目目录。 它已与 Claude Code 端到端测试；其他客户端通过服务器的[客户端设置指南](https://github.com/NPGameDev/godot-mcp-server/blob/main/docs/mcp-clients.md) 适配。 代理驱动命令行步骤；您打开编辑器并在它要求时重新连接客户端。 ```text 设置此项目的 Godot MCP 工具包： 1. 编写客户端配置（首先检查 Node >= 22）。如果此项目没有 .mcp.json， 使用“godot-mcp-toolkit”服务器条目创建它，运行 “npx -y @npgamedev/godot-mcp-server”（在 Windows 上用 cmd /c 包装）。npx 在首次连接时获取 桥梁，因此不需要全局安装；“npm install -g @npgamedev/godot-mcp-server”仅用于固定复制或离线工作。 2. 仅限全新设置：如果 addons/godot_mcp_toolkit 存在但 project.godot 没有 [editor_plugins] 条目启用它，请添加启用行，以便插件在首次启动时加载。 如果此项目已在 Godot 中打开，请告诉我通过项目设置 > 插件启用它， 不要在运行的编辑器下编辑 project.godot。 3. 然后停止并告诉我：打开项目到 Godot，确认码头显示 “[MCPServer] listening”，并重新连接您（MCP 客户端），以便加载新的配置。 4. 我确认后，运行只读探针（列出场景树或读取项目设置） 并报告您看到的内容。 ``` </details> ### 4. 连接并请求某些内容 从项目根目录启动您的 MCP 客户端。它会发现插件并自动进行身份验证。您应该看到码头的对等体计数增加。 然后尝试下面的第一个提示。这就是它产生的结果： <!-- 捕获：预 1.0，Godot 4.7，2026-07-24，人类记录（编辑器 + MCP 码头，1 个对等体连接，游戏运行）；UI 铬镜头是按照 docs/media/README.md 中的说明手动记录的。 -->  如果某一步骤没有产生其“您应该看到的内容”，请转到 [故障排除指南](docs/troubleshooting.md)。它从 60 秒的检查清单和连接性探针开始。 ## 尝试询问… 1. *"构建一个小型砖块破坏者：桨、球、砖墙、分数标签和游戏结束屏幕，然后测试它。"* 2. *"在主场景中添加一个名为 Player 的 CharacterBody2D，包含一个 Sprite2D 和一个 CollisionShape2D。"* 3. *"创建一个主菜单场景，其中包含一个启动按钮，当单击时切换到游戏场景。"* 4. *"运行游戏，然后告诉我玩家在运行时时的位置和速度。"* 最后三个在几秒钟内运行。第一个是一个真正的项目，是我们在验证版本时构建的端到端小游戏，在单个代理会话中。较大的游戏跨越多个会话，有或没有 MCP。 <!-- 捕获：预 1.0，Godot 4.5，2026-07-24，通过 runtime_screenshot 运行的 brick-breaker（飞行中）。 -->  * 上面提示 1 中的砖块破坏者。* ## 工具涵盖的内容 | 区域 | 代理可以执行的操作 | |------|----------------------| | 场景和节点 | 创建、打开、关闭、差异化场景；创建、删除、重新父节点；获取和设置任何属性；节点位置和边界的空间映射 | | 脚本和语言 | 读取、写入、编辑、验证 GDScript；LSP 支持的诊断、符号、悬停、补全、引用 | | 资源、资产、文件 | 作者 `.tres` 资源；导入二进制资产；列出和跟踪依赖项；文件夹和文件管理 | | 2D 和 3D 创作 | Tilemap 和 tileset 创作，Path2D 曲线，3D 原始体，灯光，相机，环境，GPU 粒子，导航多边形 | | 动画和音频 | AnimationPlayer 关键帧，AnimationTree 状态机和混合树，SpriteFrames，音频总线，_placeholder 纹理和声音生成 | | 测试和运行时 | 启动和停止游戏；检查实时节点，模拟输入，读取游戏日志，在运行的游戏中执行代码；编辑器和游戏的截图 | | 调试 | 断点，调试状态，崩溃诊断，编辑器控制台捕获 | | 编辑器和项目 | 项目设置，输入映射，自动加载，文件系统扫描，类数据库内省 | | 扩展 | 您自己的特定于项目的工具，在 GDScript 中注册，热加载，由代理像内置工具一样调用 | 服务器生成的[工具参考](https://github.com/NPGameDev/godot-mcp-server/blob/main/docs/tool-reference/README.md) 是权威的工具列表。哪些工具存在于哪个 Godot 版本中在随附的[兼容性指南](addons/godot_mcp_toolkit/docs/compatibility.md) 中。 ## 设计方式 几个刻意的选择塑造了工具界面： - **合并工具，计算操作。** 相关操作共享一个带有操作参数的工具，而不是每个工具一个。这使得工具列表适合每个客户端的工具预算，上下文令牌的成本更低；150+ 操作计数说明了工具包可以真正做到什么。 - **读写规范。** 每个工具都带有只读和破坏性注释，因此客户端可以自动允许安全工具并控制风险工具。只读模式可以通过一个开关隐藏每个变异工具。 - **两个通道。** 编辑器通道在正在编辑的场景上运行。运行时通道在游戏测试期间在正在运行的游戏上运行。拆分是架构的：运行时部分是导出干净的，并在调试构建外部自行禁用。 - **有些事情故意不是工具。** 任何启发式或武断的东西（场景检查、自动布局、平衡调整）都不会进入核心，因为内置工具会引起狼来了，从而侵蚀信任。扩展 API 是它们的家园。添加您自己的，官方扩展包可以在需求出现的地方跟进。 ## 扩展 在 GDScript 中注册您自己的 MCP 工具：特定于项目的帮助程序，代理调用的内置工具，具有热加载、每个工具超时和取消。目前没有固定上限您可以添加的工具数量。上限是当前系统支持的范围，每个迭代都会提高上限，使扩展更加灵活，因此您可以构建的自定义功能随时间增长。 C# 项目也支持。开始使用随附的[扩展指南](addons/godot_mcp_toolkit/docs/extending.md)。插件还捆绑了 [代理技能](addons/godot_mcp_toolkit/docs/companion-skills.md)，工作流技能和扩展编写技能，使 AI 代理更好地驱动工具包；复制一个技能文件夹到客户端的技能目录中使用它们。 ## 我们知道它有效 CI 如果以下任何数字发生变化，都会使构建失败：**112 个工具**（34 个始终开启 + 2 个元，78 个按需）**28 个组**，涵盖 **150+ 操作**；**39 个工具**在只读模式下可见。 - 每个工具都有烟雾测试覆盖（快乐路径、防护措施、错误提示），映射在服务器的[烟雾测试覆盖清单](https://github.com/NPGameDev/godot-mcp-server/blob/main/test/SMOKE-COVERAGE-MANIFEST.md) 中。跨工具状态流程作为自己的确定性套件运行（`npm run flows`），调度行为（突变序列化、取消、断开连接）作为另一个。单独的套件，单独维护。 - 每个工具也在交互式扫描中从 GDScript 进行端到端锻炼，映射在[扫描覆盖清单](Validations/SWEEP-COVERAGE-MANIFEST.md) 中。最后一次完整运行：479 个案例，Godot 4.7（2026-07-03）；参见[扫描索引](Validations/tool-sweep.md)。 - CI 在 **4.2 到 4.7** 的 Godot 版本上进行测试，在 **Windows、macOS 和 Linux** 上，在 **GDScript 和 C#（mono）** 编辑器中均有测试。地板（静态验证加单元执行）控制每次推送；完整的行为矩阵是一个可选的深层层级，不兼容 headless 的部分（截图、显示绑定输入）会跳过那里，并在本地验证。 - 五个小游戏（一个点击器、一个砖块破坏者、国际象棋、一个平台游戏和一个塔防游戏）每个都在单个代理会话中构建为发布验证。 ## 安全 默认姿势是仅限本地主机、令牌身份验证和可审计的： - **会话身份验证。** 每次插件启动时都会生成一个随机的 64 个字符的十六进制令牌。MCP 服务器从磁盘读取它并自动拒绝未经授权的 WebSocket 连接。 - **文件系统沙盒。** 默认情况下，所有文件操作都限制在 `res://`。`FileGuard` 阻止路径遍历（`..`）、绝对 OS 路径和路径解析后边界外的路径，并拒绝插件自己的源目录。（规范化是词法规范，而不是 OS 符号链接解析。） - **只读模式和每个工具的控制。** 在 `.mcp.json` 中设置 `GODOT_MCP_READ_ONLY=1`，MCP 服务器隐藏每个变异工具（代码执行、方法调用、`user://` 写入，所有 `destructiveHint` 工具）代理。 这是服务器端保证，独立于编辑器。对于更细粒度的控制，通过代理自己的权限系统（例如 `.claude/settings.json` 拒绝规则）阻止个别高风险工具。参见随附的[安全建议](addons/godot_mcp_toolkit/docs/security-recommendations.md)。 - **审计日志。** 每个工具调用都记录有 ISO-8601 时间戳和参数哈希。追加-写，写入后刷新以防止崩溃，配置的最大大小。 - **响应上限。** 脚本读取和 WebSocket 缓冲区大小限制，以防止意外的大文件外泄。 - **不受信任的信封。** 从编辑器返回的内容使用每个调用的 nonce 标签的信封，这缓解了文件内容中的提示注入。 - **仅限本地主机。** WebSocket 服务器仅绑定到 `127.0.0.1`。永远不会 `0.0.0.0`。 漏洞报告、支持的版本策略和隔离指南（容器、VM、受限帐户）位于 [SECURITY.md](SECURITY.md)。 > **免责声明：** 我们在每个层面上都进行了防御性设计，但没有软件对滥用或不可预见的漏洞免疫。该项目在 [MIT 许可证](LICENSE) 的许可下提供，没有任何保证。您在使用前必须评估它是否符合您的安全要求。 ## 运行时通道 在游戏测试期间，插件会注入一个自动加载项，打开第二个 WebSocket 服务器（默认端口 6570，从 6570 扫描到 6585）。这是运行时工具使用的通道：检查实时节点、捕获游戏截图、模拟输入、读取游戏日志、在正在运行的游戏中执行代码。 当助手使用 `game_start` 且 `wait_for_runtime: true`（默认值）时，它会自动激活，并在游戏测试结束时关闭。要固定端口，请在**编辑器进程（启动游戏）和服务器**都能看到的环境中设置 `GODOT_MCP_RUNTIME_PORT`。详细信息请参阅提供的 [高级配置指南](addons/godot_mcp_toolkit/docs/advanced_configuration.md)。 运行时工具仅存在于调试构建中：运行时部分在导出的游戏中自行禁用，捆绑的导出插件会从已导出的构建中剥离插件（及其身份验证令牌）。 ## 无界面模式 大多数工具在 `godot --headless --editor` 下工作：文件、场景、节点、脚本、ClassDB 和项目工具均无需显示即可正常运行。截图和需要运行游戏的功能会以明确的错误信息降级。规范的每个工具的无界面矩阵（在 Godot 4.2.0 至 4.7.0 上测试）位于提供的 [兼容性指南](addons/godot_mcp_toolkit/docs/compatibility.md) 中。 ## Godot 版本支持 **最低版本：** Godot 4.2 &nbsp; **推荐版本：** Godot 4.5+ &nbsp; **已测试至：** 4.7.0 | Godot 版本 | 级别 | 备注 | |-------|-------|-------| | 4.2 至 4.3 | 核心 | 除 `scene_close` 外，所有工具均可使用（包括撤销历史）； toast 通知会回退到输出面板 | | 4.4 | 完整 UI | 新增 toast 通知；`scene_close` 仍需要 4.5+ | | 4.5+ | 完整 | 所有工具和 UI 功能 | 在 4.2 至 4.4 版本中，部分工具会适应而不是失效：在引擎缺乏 API 的情况下，工具会回退到更简单的路径或回复所需的确切版本。在 4.5+ 版本中，完整的工具集无需回退即可运行。 未来 Godot 版本（4.8+）不受限制；插件使用运行时能力检查。完整的每个版本的兼容性行为，包括降级模式详细信息和 C#（.NET 编辑器）要求，在提供的 [兼容性指南](addons/godot_mcp_toolkit/docs/compatibility.md) 中。 ## 已知限制 - **动态工具加载需要处理 `tools/list_changed` 的客户端。** 通过 `discover_tools` 激活的工具仅在 MCP 客户端处理该通知时可见。当前的 Claude Code 版本在交互式和管道模式（`claude -p`）（截至 2026-07-19 验证）下均可处理；早期版本在管道模式下不处理。如果新激活的工具未出现，请重新连接或升级客户端。 - **截图捕获大小。** 完整大小的视口捕获（尤其是 3D 视口）可能超过 WebSocket 传输缓冲区，并以 `RESPONSE_TOO_LARGE` 失败。传递 `image_response_mode: "disk"` 以保存 PNG 并接收其路径，或请求较低的 `image_detail`。 - **节点焦点不会重新框选 2D 节点。** `editor_screenshot` 带有 `node_path` 会选择节点，但对于 2D 节点，不会平移或缩放视口以框选它。3D 节点焦点捕获会获取相机框选；而 2D 没有等效功能。 - **取消最小化会恢复窗口状态。** `force_foreground_*` 选项会取消最小化并在捕获前激活最小化的窗口，但窗口会恢复为窗口状态，而不是最大化状态。Godot 没有提供 API 以恢复先前的窗口模式。 - **两种并发编辑情况需要轮流进行。** 编辑器在代理工作时保持可用，大多数重叠是安全的：树编辑在手动拖动期间可以正常落地，删除检查的节点会清除检查器，Ctrl+Z 会还原最近的更改，无论是您还是代理的更改。两种情况不会合并。如果您有**未保存**的脚本编辑，并在内置编辑器中打开该脚本，而代理写入同一个文件，则磁盘写入会生效，您的缓冲区编辑会丢失，因此请在让代理编辑您正在工作的文件之前保存。如果代理重新父节点或删除您正在视口中拖动的节点，则结构更改会生效，您的拖动会以无害的 no-op 结束（可能会在输出面板中出现良性的“节点未找到”消息）。 ## 常见问题 <details> <summary><strong>它能否一次性构建整个游戏？</strong></summary> 小型游戏可以。我们的验证小游戏每个都在单个代理会话中构建（上面的示例中的砖块破坏者就是其中之一）。较大的游戏需要多个会话，无论是否使用 MCP。 </details> <details> <summary><strong>我可以将其用于商业用途吗？</strong></summary> 可以。MIT 许可证适用于插件和服务器。 </details> <details> <summary><strong>我应该将插件提交到我的游戏仓库吗？</strong></summary> 是的。捆绑的导出插件会将其剥离（及其身份验证令牌）到导出的构建中；运行时部分在调试构建之外会自行禁用。 </details> <details> <summary><strong>它在无界面模式 / CI 中工作吗？</strong></summary> 是的，但有诚实的警告：大多数工具在 `--headless --editor` 下工作；截图和需要运行游戏的功能会降级。请参阅提供的 [兼容性指南](addons/godot_mcp_toolkit/docs/compatibility.md) 中的无界面矩阵。 </details> <details> <summary><strong>C# 项目呢？</strong></summary> 支持。使用 mono（.NET）Godot 编辑器构建；标准构建无法加载 `.cs` 脚本。请参阅提供的 [兼容性指南](addons/godot_mcp_toolkit/docs/compatibility.md) 中的 C# 部分。 </details> <details> <summary><strong>多个编辑器或 git 工作树呢？</strong></summary> 是的。每个项目的实例隔离（基于哈希的子目录）和每个编辑器的端口范围。请参阅提供的 [多实例指南](addons/godot_mcp_toolkit/docs/multi-instance.md)。 </details> <details> <summary><strong>我的机器上会发生什么？</strong></summary> 不会发生任何事情。完全在本地运行，无遥测，无云服务，无帐户。 </details> ## 文档 - [文档地图](docs/README.md)：每个文档，按您想要执行的操作组织。 - [故障排除](docs/troubleshooting.md)：60 秒检查清单、连接探测、症状到修复的条目。 - [工具参考](https://github.com/NPGameDev/godot-mcp-server/blob/main/docs/tool-reference/README.md)（服务器仓库，生成）和 [令牌效率](https://github.com/NPGameDev/godot-mcp-server/blob/main/docs/token-efficiency.md)：工具表面的测量上下文成本。 - [伴侣技能效率](https://github.com/NPGameDev/godot-mcp-server/blob/main/docs/companion-skill-efficiency.md)（服务器仓库）：从捆绑的工作流技能中测量的构建时间节省。 - [客户端设置](https://github.com/NPGameDev/godot-mcp-server/blob/main/docs/mcp-clients.md)：每个客户端的配置超出 Claude Code。 - 随插件提供：[兼容性](addons/godot_mcp_toolkit/docs/compatibility.md)、[安全建议](addons/godot_mcp_toolkit/docs/security-recommendations.md)、[扩展](addons/godot_mcp_toolkit/docs/extending.md)、[捆绑的代理技能](addons/godot_mcp_toolkit/docs/companion-skills.md)、[多实例](addons/godot_mcp_toolkit/docs/multi-instance.md)、[高级配置](addons/godot_mcp_toolkit/docs/advanced_configuration.md)。 ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md)，了解环境设置、测试层和文档规则。 ## 版本发布 该项目遵循 [Semantic Versioning](https://semver.org/)。工具包插件和 MCP 服务器桥接器独立版本号；安装最新的每个版本，它们会在连接时协商兼容性（参见 [RELEASING.md](RELEASING.md) → 兼容性）。 - **npm:** `npm install -g @npgamedev/godot-mcp-server@latest` - **Godot 资产商店 / AssetLib:** 在编辑器的 AssetLib 标签中搜索“Godot MCP Toolkit”。 - **GitHub 版本发布:** 从任一仓库的版本发布页面下载以进行手动安装 参见 [RELEASING.md](RELEASING.md)，了解维护人员发布流程和版本策略。 ## 作者 **NPGameDev** · [npgamedev.com](https://npgamedev.com) · [GitHub](https://github.com/NPGameDev) 查询和请求： [np@npgamedev.com](mailto:np@npgamedev.com) ## 商标 Godot 和 Godot 徽标是 Godot 基金会的商标。该插件是一个独立的社区项目，与基金会没有任何关联或认可，并且它不是官方的 Godot 产品。该名称描述了插件运行的平台：Godot 引擎。 ## 许可证 MIT：参见 [LICENSE](LICENSE)。上游通知在 [ATTRIBUTIONS.md](ATTRIBUTIONS.md) 中。