Godot MCP

godot-mcp

让你的 AI 助手在 Godot 编辑器中拥有双眼和双手，还能实际游玩测试正在运行的游戏。

为什么选择这个？

市面上有一些 Godot MCP 服务，大多可以打开场景并操作节点。而这个项目着眼于一个更棘手的问题：**让 Agent 验证自己的工作。**运行游戏，像玩家一样操控它，观察实际发生的情况，并证明改动确实达到了预期——不用你来回传递截图和错误日志。

以下功能让这一切成为可能，也是其他项目所没有的：

• **确定性游玩测试。**冻结游戏时钟，精确推进游戏时间（或一直推进到满足某个条件），并在此期间输入操作。观察过程永远不会与游戏运行产生竞态。
• **低成本观察。**以结构化 JSON 获取实时实体状态——位置、速度、动画状态以及你自定义的数据。大多数“屏幕上发生了什么？”的问题都能得到解答，无需为截图消耗视觉 token。
• **真实输入。**支持具名操作及模拟强度、手柄按键和摇杆向量、带修饰键组合的原始按键、相对鼠标视角控制和文本输入。输入序列按精确时序运行，还能验证是否改变了游戏状态。
• **场景设置。**在正在运行的游戏中执行 GDScript：发放武器、跳到第 3 波、生成测试机器人——无需在游戏代码中预先加入调试钩子。

下面展示了 Agent 测试 Boss 战的效果：

godot_editor_edit   run frozen=true           # boot with game time frozen at frame 0
godot_exec          GameState.wave = 3        # set up the scenario worth testing
godot_game_time     step_until "tree.get_nodes_in_group('boss').size() >= 1"
godot_runtime_state digest                    # exact positions and state — no pixels, no guessing
godot_game_time     step 500ms + dodge input  # play the moment that matters
godot_editor_read   screenshot_game           # and a screenshot when it's actually worth the tokens

少点复制粘贴，多点创造。

快速开始

1. 配置你的 AI 助手

将 godot-mcp 添加到你的 MCP 客户端。配置示例请参阅安装指南（适用于 Claude Desktop、Claude Code、VSCode/Copilot 等）。简要步骤如下：

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["-y", "@satelliteoflove/godot-mcp"]
    }
  }
}

2. 安装 Godot 插件

npx @satelliteoflove/godot-mcp --install-addon /path/to/your/godot/project

在 Godot 中启用它：项目 > 项目设置 > 插件 > Godot MCP

3. 开始开发

打开你的 Godot 项目，重启 AI 助手，然后开始开发。如果无法连接，故障排除指南可以帮你解决问题。

包含内容

21 个工具，86 种操作。完整 API 文档请参阅工具参考。

工具	功能
godot_scene	打开和保存场景（直接编写 .tscn 创建新场景，然后打开）
godot_node_read / godot_node_edit	检查生效属性、完整场景树（包括实例化的子场景）并查找节点；更新属性并重新设置父节点
godot_editor_read / godot_editor_edit	编辑器状态、选中项、截图、编辑器错误日志；运行、停止、重启以及控制 2D 视口
godot_project	项目信息、设置、插件版本差异和过时设置检测
godot_animation_read / godot_animation_edit	查询动画中的关键帧；创建轨道和关键帧，并即时在编辑器中预览
godot_tilemap_read / godot_tilemap_edit	读取和编辑 TileMapLayer 单元格（在 .tscn 中以 base64 编码，只能通过桥接工具操作）
godot_gridmap_read / godot_gridmap_edit	读取和编辑 GridMap 单元格，情况相同
godot_resource	检查资源，并按类型输出：SpriteFrames、TileSet、Materials、Textures
godot_scene3d	引擎计算的 3D 变换、包围盒和可见性，便于进行空间推理
godot_docs	获取格式整洁的 Godot 文档，版本与编辑器匹配
godot_input	向正在运行的游戏注入输入：操作、手柄、原始按键、鼠标视角控制、文本
godot_profiler	指标快照和逐帧时间序列，并检测峰值
godot_runtime_state	实时游戏状态（JSON）：单次摘要、监视窗口、信号时间线
godot_game_time	冻结、逐步推进，以及推进至指定条件的游戏时钟，实现确定性观测
godot_exec	在运行中的游戏内执行 GDScript，用于设置测试场景
godot_validate_meshes	检测会伪装成光照故障的程序化网格数据静默损坏

关于设计的一点说明：工具按读写边界拆分，因此可以在客户端的权限设置中安全地自动允许每个 godot_*_read 工具（以及其他只读工具），而写入操作仍需经过许可。相关操作仍作为同一工具中的操作项，因此不会用 Agent 不会用到的定义淹没其上下文。凡是 Agent 可以直接编辑项目文件完成的操作——创建场景和节点、附加脚本、连接信号——都刻意没有重复做成工具；桥接工具负责文件无法处理的内容：编辑器状态、验证、二进制编码的单元格数据，以及运行中的游戏。--read-only 标志适用于只查看、不修改的场景。

可以提出的需求

以下是一些简单提示词，可帮助了解 Agent 能用它完成什么：

• “运行游戏并截取标题画面。布局在 1280x720 分辨率下是否正常？”
• “玩家会穿过东侧墙壁。重现这个问题，然后检查碰撞形状并告诉我原因。”
• “逐步推进游戏，直到第二波敌人出现，并给出每个敌人的位置和速度。”
• “将左摇杆保持在半档偏转状态两秒——行走动画的混合是否正确？”
• “分析十秒的游戏过程，找出导致帧时间峰值的原因。”
• “为 Player 添加受击闪光动画：颜色调制为红色，并在 0.2 秒内恢复。”

如需更丰富的运行时观测，可将关键节点添加到 mcp_watch 组，或为它们添加 _mcp_state() 方法——请参阅运行时状态指南。

工作原理

┌─────────────────┐   stdio    ┌─────────────────┐  WebSocket   ┌──────────────────┐  debugger   ┌──────────────┐
│   MCP client    │ ◄────────► │  godot-mcp      │ ◄──────────► │  Bridge addon    │ ◄─────────► │ Running game │
│ (Claude, etc.)  │            │  server (Node)  │   :6550      │  (Godot editor)  │    wire     │  (autoload)  │
└─────────────────┘            └─────────────────┘              └──────────────────┘             └──────────────┘

服务通过本地 WebSocket 与编辑器插件通信；插件通过 Godot 自带的调试器协议连接正在运行的游戏，因此游戏进程无需额外端口或设置。插件默认绑定到 127.0.0.1。完全支持 WSL2（自动检测、发现主机 IP、可配置绑定模式）——请参阅安装指南。

想了解连接生命周期、单客户端策略，或冻结时间步进的底层工作原理？架构指南对此有深入介绍。

与 minimal-godot-mcp 配合良好

@ryanmazzolini 开发的 minimal-godot-mcp 恰好涵盖了此服务未涉及的内容：用于快速静态检查 GDScript 的 LSP 诊断，以及通过 DAP 获取运行中游戏的控制台输出。此服务则涵盖所有需要编辑器桥接的功能。两者没有重叠，也不会冲突——同时运行两者，Agent 就能在获得完整编辑器和运行时控制能力的同时使用静态分析和游戏控制台。

需要注意的是：一个 Godot 编辑器同一时间只为一个 godot-mcp 客户端提供服务。额外的客户端（例如继承了 MCP 配置的子 Agent）会等待轮到自己，而不会抢占你的会话——详情请参阅故障排除。

文档

• 安装指南 — Claude Desktop、Claude Code、VSCode/Copilot 等 MCP 客户端的配置
• 迁移到 v4 — 重命名的工具、移除的操作、允许列表更新
• 故障排除 — 连接检查清单、CLI 冒烟测试、常见修复方法
• Claude Code 设置指南 — Godot 项目的 CLAUDE.md 模板
• 运行时状态指南 — 通过 mcp_watch 和 _mcp_state() 向 Agent 暴露游戏状态
• 工具参考 — 全部 21 个工具的完整 API 文档
• 架构指南 — 服务、插件和游戏桥接如何协同工作
• 贡献指南 — 开发环境设置、添加工具、发布流程
• 更新日志 — 发布历史

要求

• Godot 4.5+（插件使用了 4.5 中引入的 Logger 类）
• Node.js 20+
• 任何支持 stdio 的 MCP 客户端

开发

cd server
npm install && npm run build
npm test                # unit + schema-snapshot tests
npm run test:protocol   # wire-level smoke of the built server
npm run generate-docs

此外还有一个 Agent 评测工具集（npm run eval），它会通过无头 Claude Code 在真实项目中运行实际任务——请参阅 server/evals/README.md。它不会启动 Godot；你需要自行打开编辑器。

欢迎贡献——本项目倾向于开发能解决实际耗时问题的工具。开始大型开发前，请阅读 CONTRIBUTING.md；也可以提交 issue，我们会一起商讨合适的方案。

许可证

MIT