Godot MCP Runtime 是一个轻量级、零足迹的 TypeScript MCP 服务器，旨在让 AI 助手能够驱动 Godot 4.x 游戏引擎。它提供全面的无头编辑和完整的运行时控制，使 AI 代理不仅能编写游戏，还能检查其工作成果。
用途
该工具面向 AI 辅助游戏开发场景，让 AI 代理能够与 Godot 游戏引擎交互，执行场景编辑、运行时控制等操作。它被设计为“Godot 版的 Playwright MCP”，让代理能够自行验证修改，例如确认场景加载、按钮响应、数值更新或脚本无错误运行，而不是将验证工作交给人类。
主要能力
- 无头编辑：创建场景、添加节点、设置属性、附加脚本、连接信号、验证 GDScript，无需编辑器窗口。
- 运行时控制：通过注入的桥接（McpBridge 自动加载）提供截图、输入模拟、UI 发现、实时 GDScript 执行和函数性能分析。
- 截图：捕获视口，默认返回 960x540 预览及完整 PNG 文件。
- 输入模拟：批量按键、鼠标点击、鼠标移动、按名称或路径点击 UI 元素、Godot 动作事件、向焦点 Control 输入文本、定时等待。每个操作报告其行为。
- UI 发现：遍历实时场景树，收集所有可见 Control 节点的位置、类型、文本内容和禁用状态。
- 实时脚本执行：在游戏运行时编译并运行任意 GDScript，具有完整 SceneTree 访问权限。
- 函数性能分析：启动时设置 profiling: true，捕获 Godot 自身分析器，按自身或包含时间对最昂贵的 GDScript 函数进行排名，包含源位置和每帧平均值。
- 零足迹：无需 Godot 插件，不提交项目文件，关闭时自动清理。桥接产物位于项目下的 .mcp/godot-runtime/，服务器会将其添加到 .gitignore。
- 后台模式：run_project 时传递 background: true，Godot 窗口移至屏幕外（位置 (-9999, -9999)），物理输入被阻止：无边框、不可聚焦、鼠标穿透。程序化输入、截图和所有运行时工具照常工作。
- 手动附加模式：当游戏由 MCP 之外的方式启动（CI 管道、外部调试器、自己的 shell）时，先调用 attach_project。它注入桥接并标记项目为活动状态，而不启动 Godot。完成后使用 detach_project。注意：附加模式下 get_debug_output 不可用，因为 stdout 和 stderr 仅通过 MCP 自己启动的进程流动。
使用方式
通过 npx 零安装使用（推荐），或全局安装，或从源码克隆。支持 pnpm。配置 MCP 客户端（如 Claude Code、Claude Desktop、Cursor 或任何兼容 MCP 的客户端），添加服务器配置。如果 Godot 在 PATH 中，可省略 GODOT_PATH，服务器会自动检测。
可选环境变量包括：
- GODOT_MCP_DISABLE_ELICITATION：设为 "true" 禁用 run_project 和 run_script 的确认提示。适用于无法显示提示的客户端（如 Claude Desktop）。失败开放：操作继续并发出警告。Tier 1 安全硬阻止仍然适用。
- GODOT_MCP_STRICT：设为 "true" 硬拒绝任何原本会提示的操作，用于无人值守操作。当两者都设置时，优先于 GODOT_MCP_DISABLE_ELICITATION。
- GODOT_MCP_DISABLE_SECURITY：设为 "true" 完全关闭 run_script / run_project 安全门：无扫描、无阻止、无提示、无警告、无审计附属文件——包括 Tier 1。当两者都设置时，覆盖 GODOT_MCP_STRICT。启用此选项是人工决定，代理应拒绝代表用户设置。
Windows 路径注意事项：GODOT_PATH 必须指向 Godot 可执行文件本身，而非安装文件夹。JSON 中的反斜杠必须转义或替换为正斜杠。从包装 .bat 设置变量不会传播到 MCP 服务器——路径必须位于客户端的 env 块中。
适用场景
- AI 辅助游戏开发：让 AI 代理创建场景、节点、脚本，并通过运行游戏实时交互来检查工作。
- 自动化代理驱动测试：在窗口不可见或不可交互的情况下进行测试。
- CI 管道或外部调试器启动游戏时，通过手动附加模式使用运行时工具。
限制
- 不是游戏测试的替代品：它无法捕捉只有人类才能注意到的微妙手感问题，也不会告诉你游戏是否有趣。
- 附加模式下 get_debug_output 不可用。
- 需要 Godot 4.x 项目。
- 安全门行为受环境变量控制，某些设置需要人工决定。
更多文档
- docs/tools.md：完整工具参考，按类别分组
- docs/tool-authoring.md：添加或修改工具的标准
- docs/architecture.md：源码布局、桥接序列图、生命周期步骤、运行时产物行为
- docs/security.md：run_script / run_project 安全模型、完整规则目录、严格模式行为
该服务器基于 Coding-Solo/godot-mcp 的无头 Godot 操作基础构建，使用 Claude Code 开发。
