Godot MCP开发工具

戈多环路mcp

英文自述

godot-loop-mcp 是面向Godot4.4+的基于MCP的开发支援工具。
使用本地TCP bridge连接Godot Editor Addon和外部MCP server，以便从AI和外部客户端观察、编辑、执行和验证Godot project。

主要功能

• editor/runtime状态观测
• 编辑scene/node/script
• play_scene / stop_scene 执行循环
• 项目搜索、UID、选择、焦点
• 测试、提示、资源模板
• 功能门控截图/运行时调试界面
• 运行场景树/节点/音频播放检查
• 安全级别、审核日志、危险工具门控
• 通过GitHub Release和npm package分发

支持范围

• 戈多： 4.4+
• Node.js： 22.14.0+
• npm包： @godot-loop-mcp/server
• CI覆盖范围： 4.4.1-stable +当前最新稳定 4.x 在Windows上，每晚也在Ubuntu上
• 最新公开版：
  • GitHub发布： v0.3.1
  • npm： @godot-loop-mcp/server@0.3.1

安装

1.插件

GitHub Release的 godot-loop-mcp-addon-*.zip ，然后单击 addons/godot_loop_mcp/ 中所述修改相应参数的值。

之后，Godot的 Project Settings > Plugins 的 Godot Loop MCP 中所述修改相应参数的值。

2.服务器

npm install --save-dev @godot-loop-mcp/server

在Godot project root中启动时：

npx @godot-loop-mcp/server

从非项目根启动时 GODOT_LOOP_MCP_REPO_ROOT 中所述修改相应参数的值。

日志记录

• 默认情况下，输出到CLI/editor console Warn 控制在以上，详细日志 .godot/mcp/*.log 留下
• server/proxy/daemon的阈值是 GODOT_LOOP_MCP_CONSOLE_LOG_LEVEL 和 GODOT_LOOP_MCP_FILE_LOG_LEVEL 中所述修改相应参数的值
• addon的阈值是 Project Settings > godot_loop_mcp/log/console_level 和 godot_loop_mcp/log/file_level或同名env可覆盖

快速启动

服务器：

npx @godot-loop-mcp/server

戈多：

godot_console.exe --headless --editor --quit-after 240 --path .

期待値:

• Addon log""； Bridge handshake completed
• 服务器日志に Addon handshake completed

存储库配置

addons/godot_loop_mcp/   Godot Editor Addon
packages/server/         MCP bridge server
docs/                    運用・調査・配布ドキュメント
.github/workflows/       CI/CD

开発

npm ci --prefix packages/server
npm --prefix packages/server run typecheck

典型smoke:

$env:GODOT_LOOP_MCP_GODOT_BIN = (Get-Command godot_console.exe).Source
npm --prefix packages/server run smoke:m1
npm --prefix packages/server run smoke:m2
npm --prefix packages/server run smoke:m3
npm --prefix packages/server run smoke:m4
npm --prefix packages/server run smoke:m6

确认GUI假设：

$env:GODOT_LOOP_MCP_GODOT_GUI_BIN = (Get-Command godot.exe).Source
npm --prefix packages/server run smoke:m4:gui

运行时验证

• 在GUI editor上 play_scene 使用autoload/GodotLoopMcpRuntimeTelemetry 的双曲正切值 get_running_scene_tree / get_running_node / get_running_node_property / wait_for_runtime_condition / get_running_audio_players 可用
• get_running_scene_screenshot / get_runtime_debug_events / simulate_mouse 的runtime inspection surface是GUI editor前提
• headless editor的 play_scene 启动外部runtime process，从MCP能取得的主要是 .godot/mcp/runtime.log 是
• 直接从shell启动的Godot process不会自动连接到MCP runtime capture

文档

• 实施和quick reference: docs/implementation-milestones.md
• runtime验证的课题整理： docs/运行时验证-gaps.md
• CI/CD运用： docs/github操作cicd-plan.md
• 资产库移交： 文档/资产库租赁电子清单.md
• 设计决策存档： docs/godot-4.4-mcp-technical research.md
• 服务器包详细信息： 软件包/服务器/README.md

当前约束条件

• Godot 4.5+ 那么，优先考虑editor console capture4.4 那么 .godot/mcp 返回假back
• screenshot和 runtime.debug 是capability-gated
• dangerous tools是explicit opt-in和allowlist前提
• 手动handoff发布到Godot Asset Library

许可证

阿帕奇-2.0