Godot Mcp Runtime

Godot MCP Runtime

轻量级的 MCP 服务，为 AI Agent 提供与 Godot 游戏引擎交互的工具。支持对 Godot 4.x 项目进行全面的无头编辑和完整的运行时控制。场景、节点、自动加载和验证操作涵盖了引擎绝大多数功能；运行时桥接还支持截图、输入模拟、UI 探索，以及针对运行中场景树执行 GDScript。

AI 不只是编写游戏，还能检查自己的工作。

• 无头编辑：场景、节点、脚本、信号、验证，无需打开编辑器窗口
• 运行时控制：针对运行中的游戏进行截图、输入模拟、UI 探索、实时 GDScript 执行和函数性能分析
• 零占用：无需 Godot 插件，无需提交项目文件，关闭时自动清理

无需插件。 大多数支持运行时功能的 Godot MCP 服务都以 Godot 插件的形式提供，需要安装到项目中、提交到版本控制，并作为依赖进行管理。使用 npx 即可，无需安装或设置。

可以把它看作适用于 Godot 的 Playwright MCP。它能为游戏执行同样的操作：运行项目、截图、模拟输入、读取屏幕内容，以及针对实时场景树执行脚本。Agent 会自行验证自己的更改，而不是交给你来检查。

说明

这不能替代游戏测试。它无法发现只有人类才能察觉的细微手感问题，也无法告诉你游戏是否有趣。它能做的是让 Agent 确认场景已加载、按钮有响应、数值已更新，以及脚本运行时没有错误。对于 AI 驱动的工作流来说，检查工作至关重要。

目录

• 功能介绍
• 对比
• 快速开始
• 文档
• 致谢
• 许可证

功能介绍

这款服务是使用 Godot 开发游戏的 AI 辅助工具包。它提供了一套全面的工具，让 Agent 能够创建场景、节点、脚本等。运行时工具集支持通过运行游戏并实时与其交互来检查成果，而且不会成为项目繁重的依赖项。

专为 Agent 打造。 每款工具都经过专门设计，并能自我说明。发生错误时，响应会告知 Agent 如何修复；操作成功时，则会指引下一步。这样一来，AI 就能自行排除问题并纠正错误，无需你从旁推动。

无头编辑。 创建场景、添加节点、设置属性、附加脚本、连接信号、验证 GDScript。支持所有标准操作，无需打开编辑器窗口。

运行时桥接。 调用 run_project 或 attach_project 时，服务会将 McpBridge 注入为自动加载项。它会打开一个仅限 localhost 的 TCP 监听器（省略 bridgePort 时，两种模式都会自动选择可用端口；传入 bridgePort 可指定固定端口），并启用以下功能：

• 屏幕截图： 捕获视口。默认会内嵌返回一张 960x540 的预览图，并将完整 PNG 保存在磁盘上
• 输入模拟： 批量执行按键、鼠标点击、鼠标移动、按名称或路径点击 UI 元素、Godot 动作事件、向获得焦点的 Control 输入文本，以及定时等待。每项操作都会报告执行情况：命中的 Control、触发的信号，以及屏幕上的变化
• UI 探查： 遍历实时场景树，收集每个可见 Control 节点的位置、类型、文本内容和禁用状态
• 实时脚本执行： 游戏运行期间，编译并运行可任意访问 SceneTree 的 GDScript
• 函数性能分析： 启动时设置 profiling: true，即可捕获 Godot 自带的性能分析数据，并按自身耗时或包含子调用的总耗时，排列开销最大的 GDScript 函数，同时提供源代码位置和逐帧平均值

后台模式。 向 run_project 传入 background: true 后，Godot 窗口会移至屏幕外（位置为 (-9999, -9999)），并屏蔽物理输入：无边框、无法获得焦点、鼠标事件穿透。程序化输入、屏幕截图和所有运行时工具仍可照常使用。适用于自动化的 Agent 驱动测试，此时窗口无需显示或交互。

手动附加模式。 如果游戏由 MCP 以外的方式启动（例如 CI 流水线、外部调试器或你自己的 shell），请先调用 attach_project。它会注入桥接程序并将项目标记为活动状态，但不会启动 Godot，因此你手动启动游戏后，运行时工具即可对其进行操作。完成后使用 detach_project。

重要

附加模式下无法使用 get_debug_output。stdout 和 stderr 只会通过 MCP 自行启动的进程传递，因此 Godot 从外部启动时，没有可返回的捕获输出。如果需要调试流，请使用 run_project。

桥接程序会自动清理：调用 stop_project 或 detach_project 时，或者游戏自行退出、桥接连接断开或服务关闭时（包括客户端直接关闭连接而未调用工具的情况）。其生成的文件位于项目中的 .mcp/godot-runtime/ 下，服务会将该目录添加到 .gitignore。不会遗留自动加载项，也不会修改项目文件。

对比

Godot MCP 领域主要有两个维度：服务能否驱动_正在运行_的游戏（运行时），还是只能编辑文件；以及实现这一点需要在项目中付出什么代价。大多数提供真正运行时控制的服务，都会以 Godot 插件的形式提供，需要安装并提交到版本控制，或者需要下载自定义引擎。这个服务会临时注入桥接程序，并在关闭时将其移除，因此你可以通过原版 Godot 全面控制正在运行的游戏，且仓库中不会留下任何内容。

服务	运行中的游戏控制	占用	许可证	价格
Godot MCP Runtime	完整：截图、输入、实时场景树、脚本执行	零（npx，无需提交插件）	MIT	免费
Summer Engine	完整	下载自定义引擎 + 登录	MIT 层 / 专有引擎	核心免费，云服务收费
tugcantopaloglu/godot-mcp	完整	已提交的自动加载插件	MIT	免费
Godot MCP Pro	完整	已提交的编辑器插件	专有	$15
GDAI MCP	通过编辑器控制	已提交的编辑器插件	专有	$19
Coding-Solo/godot-mcp	否（启动 + 调试输出）	零（npx）	MIT	免费

在具备完整运行中游戏控制能力的服务中，Godot MCP Runtime 将零占用安装（无需提交插件到版本控制、无需自定义引擎、无需账号）与一条 npx 命令相结合，并从 2026 年 2 月起提供这种临时自动加载运行时桥接。完整的领域对比涵盖约 20 个服务，并为每项结论提供来源，请参阅 docs/comparison.md。

快速开始

前置条件

• Node.js v20+
• Godot 4.x

就这些。无需 Godot 插件，也无需修改项目。

配置 MCP 客户端

将以下内容添加到 MCP 客户端配置中。适用于 Claude Code、Claude Desktop、Cursor 或任何兼容 MCP 的客户端。 让你的 AI 助手调用 check_project。如果返回 Godot 版本字符串（例如 4.4.stable），则表示连接正常且可以使用。

通过 npx 零安装（推荐）：

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-runtime"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

或全局安装：

npm install -g godot-mcp-runtime

{
  "mcpServers": {
    "godot": {
      "command": "godot-mcp-runtime",
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

或从源代码克隆：

git clone https://github.com/Erodenn/godot-mcp-runtime.git
cd godot-mcp-runtime
npm install
npm run build

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["<path-to>/godot-mcp-runtime/dist/index.js"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

提示

更喜欢 pnpm？ 三种安装方式都支持 pnpm。将 npx -y godot-mcp-runtime 替换为 pnpm dlx godot-mcp-runtime，将全局安装命令替换为 pnpm add -g godot-mcp-runtime，或在构建源代码时使用 pnpm install && pnpm run build。pnpm 默认采用更强的防护措施来抵御 npm 供应链攻击；请参阅 pnpm 的供应链安全指南。

如果 Godot 已在你的 PATH 中，可以完全省略 GODOT_PATH。服务会自动检测。

可选环境变量

所有变量都设置在与 GODOT_PATH 相同的 env 块中：

变量	作用
DEBUG	设置为 "true" 时启用详细的 [DEBUG] 日志。

以下三个安全门标志共用一个维度（完整说明请参阅 docs/security.md），且名称太长，在表格中容易换行混乱，因此改用列表展示：

• GODOT_MCP_DISABLE_ELICITATION - 设置为 "true" 时，禁用对 run_project 和 run_script 的确认提示。如果客户端无法显示 elicitation 提示（例如会自动取消这些提示的 Claude Desktop），请使用此选项。失败时默认放行：操作会在发出警告后继续。第 1 级安全硬性拦截仍然生效。
• GODOT_MCP_STRICT - 设置为 "true" 时，会硬性拒绝所有原本需要提示确认的操作，适用于无人值守运行。若同时设置了 GODOT_MCP_DISABLE_ELICITATION，则此选项优先。
• GODOT_MCP_DISABLE_SECURITY - 设置为 "true" 时，会完全关闭 run_script/run_project 安全门：不扫描、不拦截、不触发 elicitation、不发出警告、不生成审计附属文件——包括第 1 级安全措施。若同时设置了 GODOT_MCP_STRICT，则此选项优先。是否启用由人类决定——Agent 不应代替用户设置此选项。

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-runtime"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>",
        "GODOT_MCP_DISABLE_ELICITATION": "true"
      }
    }
  }
}

重要

Windows 路径注意事项。 GODOT_PATH 必须指向 Godot 可执行文件本身，而不是其安装文件夹。JSON 中的反斜杠必须转义，或替换为正斜杠：

"GODOT_PATH": "D:\\Godot\\Godot_v4.4-stable_win64.exe"
// 或等效地
"GODOT_PATH": "D:/Godot/Godot_v4.4-stable_win64.exe"

从包装器 .bat 设置变量不会将其传递给 MCP 服务——路径必须放在上方客户端的 env 块中。

文档

• docs/tools.md：完整的工具参考，按类别分组
• docs/tool-authoring.md：添加或修改工具的规范
• docs/architecture.md：源代码布局、桥接时序图、生命周期步骤、运行时产物行为
• docs/security.md：run_script / run_project 安全模型、完整规则目录、严格模式行为

致谢

基于 Coding-Solo/godot-mcp 为无头 Godot 操作奠定的基础构建。

使用 Claude Code 开发。

许可证

MIT