godot-peek-mcp

🚀 Godot Peek MCP

Godot Peek MCP 是一个用于深入查看 Godot 编辑器运行时状态的 MCP 服务器。它可以运行场景、捕获输出、检查调试器状态，为开发者提供了强大的运行时可见性。

🚀 快速开始

为什么需要另一个 Godot MCP？

其他 Godot MCP 所封装的编辑器操作，大语言模型（LLMs）本身就能完成。例如，Claude 可以直接编辑 .tscn、.tres 和 .gd 文件，当它能够直接编辑场景文件时，就不需要借助工具来“添加节点”。而本 MCP 专注于运行时可见性，包括输出面板、调试器状态和截图等，这些通常需要与编辑器进行交互才能获取的内容。

安装步骤

下载、复制、连接，仅需三步。

1. 下载

从 Releases 为你的操作系统下载对应的版本： | 操作系统 | 文件 | | ---- | ---- | | Linux x86_64 | godot-peek-mcp-vX.X.X-linux-x86_64.tar.gz | | macOS Apple Silicon | godot-peek-mcp-vX.X.X-macos-arm64.tar.gz |

将其解压到方便的位置（例如 ~/tools/godot-peek-mcp/），你将得到：

• godot-peek-mcp — MCP 服务器二进制文件
• addons/godot_mcp/ — Godot 插件

2. 安装 Godot 插件

将 addons/godot_mcp 文件夹复制到你的 Godot 项目中，最终路径为 your-project/addons/godot_mcp/。然后在 Godot 中启用它：项目 > 项目设置 > 插件 > Godot Peek MCP > 启用。

你应该会在输出面板中看到类似以下内容（套接字名称由你的项目目录派生而来）：

GodotPeekPlugin: listening on /tmp/godot-peek-my-game.sock

3. 注册 MCP 服务器

选择你的 MCP 客户端：

claude mcp add godot-peek ~/tools/godot-peek-mcp/godot-peek-mcp

{
  "mcpServers": {
    "godot-peek": {
      "command": "/home/YOUR_USER/tools/godot-peek-mcp/godot-peek-mcp"
    }
  }
}

{
  "mcpServers": {
    "godot-peek": {
      "command": "/home/YOUR_USER/tools/godot-peek-mcp/godot-peek-mcp"
    }
  }
}

{
  "mcpServers": {
    "godot-peek": {
      "command": "/home/YOUR_USER/tools/godot-peek-mcp/godot-peek-mcp"
    }
  }
}

完成以上步骤后，你就可以开始使用了。

macOS：清除隔离

macOS 可能会阻止从互联网下载的未签名二进制文件。如果你收到安全警告，请运行以下命令：

xattr -cr ~/tools/godot-peek-mcp/godot-peek-mcp
xattr -cr ~/your-project/addons/godot_mcp/bin/

✨ 主要特性

• 场景控制：运行主场景、当前场景或特定场景，停止游戏。
• 变量覆盖：在启动时设置自动加载变量（例如启用调试模式）。
• 输出捕获：读取输出面板内容。
• 调试器集成：获取错误信息、堆栈跟踪、局部变量和性能监控数据。
• 调试器控制：设置断点、单步执行代码、暂停/继续执行。
• 运行时检查：查看运行中游戏的节点树和属性。
• 截图：捕获编辑器视口或运行中游戏的截图。
• 表达式求值：在运行中的游戏中计算任意 GDScript 表达式。

📦 安装指南

从源码构建

如果你想从源码构建而不是使用发布版本，可以执行以下命令：

# go mcp server
go build -ldflags="-s -w" -o godot-peek-mcp ./cmd/godot-peek-mcp

# c++ extension (requires godot-cpp — set GODOT_CPP_PATH or defaults to ~/Code/godot-cpp)
cd extension && scons platform=linux target=editor

💻 使用示例

场景控制

| 工具 | 描述 | 参数 | | ---- | ---- | ---- | | run_main_scene | 运行主场景（F5） | timeout_seconds，overrides（可选） | | run_scene | 运行特定场景 | scene_path，timeout_seconds，overrides（可选） | | run_current_scene | 运行当前打开的场景 | timeout_seconds，overrides（可选） | | stop_scene | 停止正在运行的游戏 | 无 | | restart_scene | 停止并使用上次运行的相同设置重新运行 | 无 |

overrides：在启动时设置自动加载变量。格式：{"AutoloadName": {"property": value}} 示例：{"DebugManager": {"debug_mode": true}}

输出与调试

| 工具 | 描述 | 参数 | | ---- | ---- | ---- | | get_output | 获取输出面板内容 | clear，new_only（可选） | | get_debugger_errors | 获取调试器错误选项卡内容 | 无 | | get_debugger_stack_trace | 获取在错误/断点处暂停时的堆栈跟踪 | 无 | | get_debugger_locals | 获取在错误/断点处暂停时的局部变量 | frame_index（可选，0 表示顶层） | | get_monitors | 获取性能监控数据（如 FPS、内存等） | 无 | | get_remote_scene_tree | 获取运行中游戏的节点树 | max_depth（可选，0 表示无限制） | | get_remote_node_properties | 获取节点属性 | node_path（例如 /root/game/Player） |

截图

| 工具 | 描述 | 参数 | | ---- | ---- | ---- | | get_screenshot | 捕获编辑器或游戏截图 | target："editor" 或 "game" |

调试器控制

| 工具 | 描述 | 参数 | | ---- | ---- | ---- | | set_breakpoint | 设置或清除断点 | path，line，enabled | | clear_breakpoints | 清除所有断点 | 无 | | get_debugger_state | 检查是否暂停/活动/可调试 | 无 | | debug_continue | 继续执行 | 无 | | debug_step | 单步进入/跳过/跳出 | mode："into"，"over"，"out" | | debug_break | 暂停执行 | 无 |

注意：断点仅适用于 Godot 的内置脚本编辑器。如果使用外部编辑器，断点将不会触发。

表达式求值

| 工具 | 描述 | 参数 | | ---- | ---- | ---- | | evaluate_expression | 在运行中的游戏中计算 GDScript 表达式 | expression（例如 get_node("/root/Main/Player").health） |

使用此功能可以查询游戏状态、设置变量或调用方法，而无需添加调试代码。

📚 详细文档

大语言模型用户提示

• 迭代调试：运行场景 → 检查输出 → 修复代码 → 重复。run_* 工具会自动检测启动崩溃并返回堆栈跟踪。
• 使用覆盖进行测试：使用 {"DebugManager": {"debug_mode": true}} 运行，无需编辑代码即可启用调试功能。
• 运行时检查：使用 get_remote_scene_tree 查看实例化的内容，然后使用 get_remote_node_properties 检查值。
• 自动停止测试：使用 timeout_seconds 短暂运行，然后检查 get_output。适用于自动化测试循环。
• 截图用于视觉错误检查：get_screenshot target=game 可以显示玩家看到的内容。
• 表达式求值：无需打印语句即可查询任何游戏状态。例如 evaluate_expression "get_tree().current_scene.name" 或修改状态：evaluate_expression "get_node('/root/Main/Player').set('health', 100)"（使用 .set() — 赋值运算符在 Expression 类中不起作用）。注意：如果表达式触发运行时错误，工具调用将超时，因为游戏在响应之前会崩溃。

导出游戏

MCP 插件仅适用于编辑器。要导出游戏，请排除扩展文件，否则构建的游戏在启动时会出错：

导出 > 资源 > 排除过滤器：添加 addons/godot_mcp/bin/*, addons/godot_mcp/godot_peek.gdextension, addons/godot_mcp/plugin.*

运行时辅助脚本 (peek_runtime_helper.gd) 会被包含在内，因为它被注册为自动加载脚本，但在导出构建中会自动跳过初始化。

注意事项

• 输出：从输出面板读取内容，包括 print()、push_error()、push_warning() 和编辑器消息。
• 调试器工具：从相应的调试器选项卡获取数据。frame_index 用于选择局部变量的堆栈帧（0 表示顶层）。重要：get_debugger_stack_trace 和 get_debugger_locals 仅在游戏因运行时错误或断点暂停时才有数据 — 在正常执行期间调用它们将返回空结果。
• 远程检查：get_remote_scene_tree 和 get_remote_node_properties 仅在游戏运行时有效。
• 监控数据：get_monitors 显示引擎性能数据，如 FPS、内存使用、绘制调用、物理统计等。
• 截图：保存到 /tmp/godot_peek_*.png。编辑器截图捕获活动的 2D/3D 视口。游戏截图需要插件自动添加的自动加载脚本。

🔧 技术细节

架构

┌─────────────────────┐     stdio      ┌─────────────────────┐
│   Claude Code #1    │◄──────────────►│  Go MCP Server #1   │──┐
└─────────────────────┘                └─────────────────────┘  │
┌─────────────────────┐     stdio      ┌─────────────────────┐  │ Unix socket
│   Claude Code #2    │◄──────────────►│  Go MCP Server #2   │──┤ /tmp/godot-peek-<project>.sock
└─────────────────────┘                └─────────────────────┘  │
                                            ...                 │
                                       ┌────────────────────────▼┐
                                       │  C++ GDExtension        │
                                       │  (addons/godot_mcp)     │
                                       └────────────┬────────────┘
                                                    │ UDP (game features)
                                                    │ port 6971
                                       ┌────────────▼────────────┐
                                       │  Runtime Helper         │
                                       │  (running game)         │
                                       └─────────────────────────┘

多个 MCP 客户端会话可以同时连接。每个会话会生成自己的 Go MCP 服务器进程，C++ 扩展会同时接受所有连接。

要求

• Godot 4.4、4.5 或 4.6
• Linux x86_64 或 macOS arm64（Apple Silicon）