Godot MCP Loop

godot-mcp-loop

让 AI Agent 编辑你的 Godot 4 游戏，并检查自己的成果。 一个 MCP 服务和 Godot 编辑器插件，专注于验证闭环：修改 → 运行 → 观察 → 判断。

日本語 README · 工具 · 场景 · 客户端 · 安全 · 协议

有很多 Godot MCP 服务可以让 Agent 编辑场景，却很少能让它确认修改是否生效。 godot-mcp-loop 为 Agent 提供一套游戏测试工具：启动游戏、发送真实输入、等待条件满足、读取实时状态、截图、收集错误；此外还支持声明式场景测试，并返回包含失败值的通过／失败报告。编辑操作刻意保持保守：每项修改都可撤销、可预览、应用前经过验证，并且受限于你的项目范围。

Agent 可以做什么

godot_status                                    → editor connected, Godot 4.7.2, main.tscn open
script_write res://player.gd (dry_run)          → unified diff; compile errors with line numbers if any
script_write res://player.gd                    → written (undoable)
game_run                                        → game running, runtime connected
game_input [{action: move_right, hold_ms: 1000}]
game_wait_for Player position:x > 250           → met after 0.8 s
screenshot                                      → (image)
logs_read source=game min_level=error           → []
scenario_run res://tests/move_right.yaml        → PASSED (7/7 steps)

亮点

• 闭环：game_run、game_input（动作、按键、鼠标，支持真实时序；可逐帧记录数值）、game_wait_for （逐帧检查，超时时报告最后一个值）、game_query、screenshot、logs_read。
• 场景测试：YAML/JSON 游戏测试 → 每个步骤的通过／失败结果、失败截图、游戏错误。详情。
• 安全编辑：每次编辑都会进入 Godot 的撤销历史记录；edit_undo 只会撤销通过 MCP 执行的编辑； 全程支持 dry_run；GDScript 写入前会先编译；更改前会先验证属性值。
• 沙箱隔离：仅限 localhost 的桥接，使用会话专属令牌；仅允许 res:// 路径；禁止写入 .godot/、.git/ 或插件目录；不提供任意代码执行工具。安全说明。
• 错误时不会卡死：Godot 的调试器会在脚本错误时暂停游戏；插件会记录错误并继续运行，让 Agent 能看到错误，而不是一直等待。
• 游戏中不额外占用端口：游戏通过 Godot 自带的调试器连接与编辑器通信。
• 41 个专用工具，而不是数百个，便于模型有效使用。

要求

• Godot 4.7（已在 4.7.2 上测试）。4.5–4.6 应该也能使用——插件需要 4.5 新增的 Logger API——但目前尚未测试。
• Node.js 20+
• MCP 客户端：Claude Code、Cursor、Claude Desktop、Codex、Hermes Agent 等……

安装

作为 Claude Code 插件（Claude Code 2.1.275+；会询问一次 Godot 项目路径）：

/plugin install godot-mcp-loop --marketplace AI-osho/godot-mcp-loop

该插件会注册 godot-loop MCP 服务和 Agent 技能；它会运行 npm 包，因此请确保它复制到项目中的 addon 与服务使用相同版本。

使用 npm（Node.js 20+）： 使用 npm（Node.js 20+）：

已列入官方 MCP Registry，名称为 io.github.AI-osho/godot-mcp-loop — 可以浏览 Registry 的客户端可直接从那里添加；以下步骤相同。

1. Addon — addon 必须与服务版本一致，因此请让服务将其复制到项目中并启用：

   npx -y godot-mcp-loop@latest install-addon /ABS/my-game --skill
   

   --skill 还会添加 Agent 技能（见下方第 5 步）。该命令会打印接下来要使用的版本。
2. 客户端 — 使用该版本注册服务，例如 Claude Code：

   claude mcp add godot-loop -- npx -y godot-mcp-loop@<version> --project /ABS/my-game
   

   其他客户端：参见 docs/clients.md。
3. 在 Godot 编辑器中打开项目，并让 Agent 调用 godot_status。

从源代码安装：

1. Addon — 将 addons/mcp_loop 复制到项目的 addons/ 文件夹中，然后启用 Project › Project Settings › Plugins › MCP Loop。该插件会注册自动加载项 MCPLoopRuntime （在导出的游戏中处于非活动状态）。
2. 服务 —

   git clone https://github.com/AI-osho/godot-mcp-loop.git
   cd godot-mcp-loop/server && npm ci && npm run build
   

3. 客户端 — 例如 Claude Code：

   claude mcp add godot-loop -- node /ABS/godot-mcp-loop/server/dist/index.js --project /ABS/my-game
   

   其他客户端：参见 docs/clients.md。
4. 在 Godot 编辑器中打开项目，并让 Agent 调用 godot_status。
5. Agent 技能（推荐）— 将 .claude/skills/godot-mcp-loop 复制到项目的 .claude/skills/（或者复制到 ~/.claude/skills/，以供所有项目使用）。它会教 Agent 使用循环、通过 game_step 进行确定性检查、场景模式以及像素艺术。它遵循 Agent Skills 格式，因此其他能够读取技能的 Agent 也可以使用它。

开始一个新游戏项目

scripts/new-game.sh ~/games/my-game --name "My Game" --register-claude

会创建一个启用了 addon 的 Godot 项目，其中包含 Agent 技能、简短的 AGENTS.md / CLAUDE.md 文件、一个 scenarios/ 文件夹和初始 git 提交，并为该文件夹向 Claude Code 注册 MCP 服务（单独的 Claude Code 配置可使用 --claude-config DIR）。然后使用 godot -e --path ~/games/my-game 打开项目。

对于较长时间的构建，项目还会获得 PROGRESS.md（目标、状态、已完成、下一步、决策、已知问题），Agent 会持续更新该文件；以及 Claude Code 项目设置（.claude/settings.json）：会话启动钩子会将 PROGRESS.md、最近的提交和未提交的更改打印到 Agent 的上下文中——在启动、恢复会话、执行 /clear 后以及上下文压缩后均会如此；godot-loop 工具无需权限提示即可运行；破坏性 Shell 命令（rm -rf、强制推送、git reset --hard、git clean）则会被拒绝。接受 Claude Code 针对此文件夹的信任提示后，它就会应用允许规则。

试用演示

此仓库本身就是一个 Godot 项目，包含一个迷你平台游戏 （examples/platformer，方向键 + Space）。在 Godot 中打开它，将服务指向仓库根目录，并让你的 Agent “对 res://examples/platformer/scenarios/move_right.yaml 运行 scenario_run”——然后试试 intentional_failure.yaml，查看失败报告。

五分钟快速体验

1. 安装插件到项目文件夹中（它会复制 addons/mcp_loop、启用插件，并将 Agent 技能放入 .claude/skills/）：

   cd my-game && npx -y godot-mcp-loop@latest install-addon . --skill
   

2. 在 Godot 中打开项目（4.5+）：godot -e --path . — 桥接会随编辑器启动，并在 127.0.0.1 上监听。
3. 将 MCP 客户端连接到 npx -y godot-mcp-loop@latest --project /absolute/path/to/my-game，然后请求 godot_status：它应该会报告 Godot 版本、项目以及编辑器中打开的场景。
4. 提出一项更改和一项检查：“在关卡中添加一枚金币，然后运行 scenario_run {"path": "res://scenarios/coins.yaml"}”。如果某个步骤失败，返回结果会包含观测值和截图。
5. 记录结果：使用 "movie": {} 和 "save_to": "res://qa/evidence/tour" 运行同一场景，然后打开 qa/evidence/tour/movie.gif — 查看完整运行过程，以及关键帧的联系表。

高级示例

五款完整游戏位于 examples/ 中。每款游戏都由 AI Agent 通过 godot-mcp-loop 根据单条提示词端到端生成 — 包括代码、NES 风格像素美术（image_write）、输入操作、测试钩子和回归场景 — 随后经过独立验证：每个场景都能通过，随机输入运行也不会记录任何错误。

3D 示例随软件包一同提供，因此无需克隆此仓库即可打开：

npx -y godot-mcp-loop@latest sample marble-3d ./marble-3d
cd marble-3d && npx -y godot-mcp-loop@latest install-addon . --skill && godot -e --path .

这款游戏是 3D 工具的开发基础：包含七个场景（7_gap_needs_jump.yaml 证明无法滚过缺口）、追逐摄像机、金币、检查点、生命和限时通关。运行 npx -y godot-mcp-loop@latest sample 可列出所有内置内容。

	游戏	生成者	行数	场景数
	方块下落 — 方块下落益智游戏：采用 SRS 风格旋转和踢墙机制、幽灵方块、关卡与计分，以及固定种子的方块顺序	Claude Opus 5.5（Claude Code）	381 行	4
	纵向射击游戏 — 5 波敌人，共 4 种类型；拥有 3 种攻击模式的 Boss、爆炸效果、滚动星空和 11 个精灵	Claude Opus 5.5（Claude Code）	805 行	4
	横版卷轴游戏 — 加速度和可变跳跃、包含坑洞与移动平台的 8 屏关卡、可踩踏的敌人、金币、终点、3 层视差背景和 12 个精灵	DeepSeek V4.1 Flash（Claude Code）	967 行	4
	RPG《星剣のルカ》 — NES 风格 RPG，拥有原创故事和角色阵容：标题与序章、网格移动、NPC 对话、随机遇敌、正面视角战斗（包含法术、道具、逃跑和升级）、Boss 与结局（日文文本）	DeepSeek V4.1 Flash（Claude Code）	2,284 行	6
	大理石跑酷 — 首个 3D 示例：大理石在坡道和缺口上滚动，包含 10 枚金币、检查点和生命、追逐摄像机、限时通关和完整 HUD	DeepSeek V4.1 Flash（Claude Code）	676 行	7

使用 game_run {"scene": "res://examples/shooter/shooter.tscn"} 来玩一款游戏（或打开场景并按 F6），并使用 scenario_run {"path": "res://examples/shooter/scenarios/4_boss_clear.yaml"} 重放其检查 — 或通过 {"path": "res://examples/shooter/scenarios"} 重放全部检查。操作方式和详情见：examples/README.md。

工具

区域	工具
状态	godot_status、project_info、project_list、project_connect（切换项目）
编辑器	editor_launch（查找 Godot 并打开项目）、editor_quit
场景	scene_open、scene_create、scene_save、scene_tree
节点	node_add、node_delete、node_get、node_set
脚本	script_read、script_write、script_edit、script_attach
文件和资源	file_write（YAML/JSON/文本）、image_write（像素艺术 PNG）、input_action_set、project_setting_set（主场景、视口、拉伸）
撤销	edit_undo
运行和观察	game_run、game_stop、game_query、game_ui_audit、game_in_view、game_ray、game_contacts、game_input、game_wait_for、game_set、game_call、game_pause、game_step、logs_read、screenshot
构建	project_export（从预设导出发行版本，仅导出到 res://build/，不使用 shell）
评测	scenario_run（证据文件夹，movie → GIF + 联系表）、test_run（GUT / GdUnit4 单元测试）

完整参考：docs/tools.md。

无头模式 / CI

在 项目设置 › 编辑器 › 运行 › 主运行参数 中添加 --headless，即可在没有窗口的情况下运行游戏（除 screenshot 外，其他功能均可使用）。该仓库自身的 CI 会在 Linux 上运行无头编辑器和无头游戏，以执行端到端测试——详见 .github/workflows/ci.yml。

开发

scripts/test-godot-unit.sh                   # GDScript unit tests (headless)
cd server && npm run typecheck && npm test   # TypeScript unit tests
npm run build && npm run test:e2e            # end-to-end against a real headless editor + game
E2E_GAME_WINDOW=1 npm run test:e2e           # same, with game windows (enables screenshot checks)

限制

• 每个编辑器同一时间只能连接一个 MCP 客户端（新连接会替换旧连接）。
• script_write 仅验证 GDScript；引用自身新建的 class_name 的脚本，编译检查可能会稍微宽松一些。
• 暂不支持 C# 项目。

许可证

MIT © OSHO