Godot Peek MCP
MCP服务器，用于窥探Godot编辑器运行时。运行场景，捕获输出，检查调试器状态。
为什么选择另一个Godot MCP？
其他Godot MCP包装LLM已经可以执行的编辑器操作。Claude可以编辑 .tscn, .tres，以及 .gd 它不需要工具来“添加节点”，只需要编辑场景文件即可。
本MCP侧重于 运行时可见性：输出面板、调试器状态、屏幕截图。通常需要与编辑器交互的内容。
设置
下载、复制、连接。三个步骤。
1.下载
从以下位置获取适用于您的操作系统的版本 发布:
| OS | 文件 |
|---|---|
| Linux x86_64 | godot-peek-mcp-vX.X.X-linux-x86_64.tar.gz |
| macOS苹果硅 | 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.sock3.注册MCP服务器
选择您的MCP客户端：
Claude Code
从Godot项目目录运行此命令，指向 godot-peek-mcp 您在步骤1中提取的二进制文件：
claude mcp add godot-peek ~/tools/godot-peek-mcp/godot-peek-mcp套接字路径是从工作目录名称自动派生出来的。重新启动Claude Code或运行 /mcp 以验证连接。
Cursor
创建或编辑 .cursor/mcp.json 在项目根目录中：
{
"mcpServers": {
"godot-peek": {
"command": "/home/YOUR_USER/tools/godot-peek-mcp/godot-peek-mcp"
}
}
}确保从Godot项目目录打开项目，以便工作目录匹配。
Windsurf
编辑 ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"godot-peek": {
"command": "/home/YOUR_USER/tools/godot-peek-mcp/godot-peek-mcp"
}
}
}Claude Desktop
编辑配置文件(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上， ~/.config/Claude/claude_desktop_config.json 在Linux上）：
{
"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
工具
场景控制
| 工具 | 说明 | 参数 |
|---|---|---|
run_main_scene | 运行主场景（F5） | timeout_seconds, overrides （可选） |
run_scene | 运行特定场景 | scene_path, timeout_seconds, overrides （可选） |
run_current_scene | 运行当前打开的场景 | timeout_seconds, overrides （可选） |
stop_scene | 停止跑步游戏 | 无 |
restart_scene | 停止并使用上次运行时的相同设置重新运行 | 无 |
覆盖：在启动时设置自动加载变量。格式： {"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 （例如/根/游戏/玩家） |
截图
| 工具 | 说明 | 参数 |
|---|---|---|
get_screenshot | 捕获编辑器或游戏 | target：“编辑器”或“游戏” |
调试器控制
| 工具 | 说明 | 参数 |
|---|---|---|
set_breakpoint | 设置或清除断点 | path, line, enabled |
clear_breakpoints | 清除所有断点 | 无 |
get_debugger_state | 检查是否暂停/活动/可调试 | 无 |
debug_continue | 继续执行 | 无 |
debug_step | 进入/结束/退出 | mode：“进入”、“结束”、“退出” |
debug_break | 暂停执行 | 无 |
注： 断点仅适用于Godot的内置脚本编辑器。如果使用外部编辑器，断点不会触发。
表达式求值
| 工具 | 说明 | 参数 |
|---|---|---|
evaluate_expression | 在运行游戏中评估GDScript | expression （例如。 get_node("/root/Main/Player").health) |
使用此选项可以查询游戏状态、设置变量或调用方法，而无需添加调试代码。
LLM用户提示
迭代调试：跑步场景→ 检查输出→ 修复代码→ 重复。这 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-
.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（苹果硅）
从源头构建
如果你想从源代码构建而不是使用版本：
# 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