Godot Peek MCP

🚀 Godot Peek MCP

Godot Peek MCP 是一個用於深入查看 Godot 編輯器運行時狀態的 MCP 服務器。它可以運行場景、捕獲輸出、檢查調試器狀態，為開發者提供了強大的運行時可見性。

🚀 快速開始

為什麼需要另一個 Godot MCP？

其他 Godot MCP 所封裝的編輯器操作，大語言模型（LLMs）本身就能完成。例如，Claude 可以直接編輯 .tscn、.tres 和 .gd 文件，當它能夠直接編輯場景文件時，就不需要藉助工具來“添加節點”。而本 MCP 專注於運行時可見性，包括輸出面板、調試器狀態和截圖等，這些通常需要與編輯器進行交互才能獲取的內容。

安裝步驟

下載、複製、連接，僅需三步。

1. 下載

從 Releases 為你的操作系統下載對應的版本：

將其解壓到方便的位置（例如 ~/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

💻 使用示例

場景控制

overrides：在啟動時設置自動加載變量。格式：{"AutoloadName": {"property": value}} 示例：{"DebugManager": {"debug_mode": true}}

輸出與調試

截圖

調試器控制

注意：斷點僅適用於 Godot 的內置腳本編輯器。如果使用外部編輯器，斷點將不會觸發。

表達式求值

使用此功能可以查詢遊戲狀態、設置變量或調用方法，而無需添加調試代碼。

📚 詳細文檔

大語言模型用戶提示

• 迭代調試：運行場景 → 檢查輸出 → 修復代碼 → 重複。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）