Open Godot MCP

開源、免費、全功能的 Model Context Protocol（MCP）server，讓 AI 自主開發、測試、除錯 Godot 遊戲——包含真實遊戲操作、確定性 playtesting、連線遊戲測試、DAP 除錯、LSP 整合、Token 效率設計。100% MIT 授權，無 freemium，無付費牆。

Languages: 繁體中文（本檔）| English | 简体中文 | 日本語 | 한국어 | Español | Français | Deutsch | Русский | Português-BR | Polski | Italiano | Türkçe | ภาษาไทย | Tiếng Việt | Bahasa Indonesia | Українська | Nederlands | العربية | हिन्दी

Open Godot MCP 是什麼？

Open Godot MCP 是一個開源的 Model Context Protocol server，將 AI 程式助手（Claude、GPT、Cursor、Windsurf 等）連接到 Godot Engine 編輯器。它讓 AI 能夠寫程式、運行遊戲、測試玩法、在斷點除錯、檢查變數、驗證修復——全部自主完成，無需人工介入。

與只能編輯場景的現有 Godot MCP 不同，Open Godot MCP 讓 AI 真的玩遊戲——透過確定性 playtesting（凍結時鐘 → step 時間 → 觀察狀態 → 驗證結果）。它是唯一支援連線遊戲測試、DAP 除錯器整合、LSP 程式碼智慧的 Godot MCP。

為什麼要做這個

市面上的 Godot MCP 都有缺陷：

適合誰用？

• Godot 4 遊戲開發者——想讓 AI 幫忙寫程式、測試、除錯

• AI 輔助程式設計師（Claude、Cursor、Windsurf、VS Code MCP 使用者）——在 Godot 專案上工作

• 獨立遊戲工作室——需要自動化 playtesting，不想自己寫測試框架

• 連線遊戲開發者——需要測試網路同步、延遲、peer 行為

• 開源倡議者——想要完全免費、無付費牆的 MCP server

使用情境

核心能力

1. 確定性 Playtesting（解決「AI 看不到遊戲運行」）

AI 不只寫程式，還能自己玩遊戲驗證修復：

godot_game play frozen=true                    # 啟動遊戲（凍結時鐘）
godot_exec eval code="GameState.wave = 3"      # 設定測試場景
godot_game_time step_until "boss.size() >= 1"  # 等待 Boss 出現
godot_runtime_state digest                     # 觀察狀態（JSON，不燒 vision token）
godot_game_time step ms=500 + dodge input      # 播放關鍵時刻
godot_screenshot game                          # 只在值得時截圖

2. 連線遊戲測試（獨有功能——其他 Godot MCP 都沒有）

所有現有 Godot MCP 都缺的能力：

godot_network launch_instance role="host"      # 啟動伺服器
godot_network launch_instance role="client"    # 啟動客戶端
godot_network network_condition latency=200    # 注入 200ms 延遲
godot_network sync_state                       # 驗證多實例同步
godot_network simulate_peer count=50           # 壓力測試 50 個 peer

3. Token 效率

每個工具都有省 token 設計：

• cheap observation：JSON state digest 取代截圖（省 90% token）

• diff 回傳：只回傳變更部分

• 截圖壓縮：JPEG/WebP + 存磁碟（不進 context）

• read/write 分離：read auto-allow，write gate

• 批次操作：一次 round-trip 完成多個操作

4. 連線穩定

解決現有 MCP「時常連線不到」的問題：

• 可配置 port（env > EditorSettings > 自動避讓）

• Windows Port Reservation 偵測（避開 Hyper-V/WSL2/Docker 保留 port）

• 心跳機制（主動偵測死連線）

• 智慧重連（指數退避 + 最大次數 + UI 通知）

5. 完整除錯

• DAP（Debugger Adapter Protocol）：breakpoint、step、變數 inspect（stack_trace、variables、evaluate）

• LSP（Language Server Protocol）：靜態診斷、自動完成、go-to-definition

• Profiler：效能快照、時序分析、spike 偵測

快速開始

1. 安裝 MCP Server

uv tool install open-godot-mcp
# 或
pip install open-godot-mcp

2. 設定 AI Client

{
  "mcpServers": {
    "open-godot-mcp": {
      "command": "open-godot-mcp"
    }
  }
}

3. 開啟 Godot 專案

Addon 會自動注入。開啟 AI Client 開始用。

完整安裝指南見 Docs/06-Installation/Guide.md。

工具清單

~30 tools，~130 actions。read/write 分離設計。

完整 API 見 Docs/02-Tools/Index.md。

與現有 Godot MCP 比較

常見問題

什麼是 Model Context Protocol（MCP）？

Model Context Protocol 是一個開放標準，讓 AI 助手連接外部工具和資料來源。Open Godot MCP 是一個 MCP server，將 AI 連接到 Godot Engine 編輯器。

支援哪些 Godot 版本？

Godot 4.5 及更新版本。Addon 使用 Godot 4.x API，包含 EditorDebuggerPlugin、EditorInspector、debugger message channel。

哪些 AI 客戶端相容？

任何 MCP 相容客戶端：Claude Desktop、Cursor、Windsurf、VS Code（MCP 擴充）、Continue、Zed，以及任何支援 Model Context Protocol 標準的客戶端。

支援 C#（Godot .NET 版）嗎？

是的。C# 語法檢查和編譯驗證已支援。見 Docs/08-CSharp-Support/。

跟其他 Godot MCP 有什麼不同？

Open Godot MCP 是唯一支援連線遊戲測試、DAP 除錯器整合（斷點、stack trace、變數檢查）、LSP 程式碼智慧的 Godot MCP。它也有最全面的 Token 效率設計。

真的免費嗎？

是的。100% MIT 授權，無 freemium 模式，無付費牆，無功能限制。所有功能對所有人免費。

AI 真的能玩遊戲嗎？

是的。透過確定性 playtesting，AI 可以凍結遊戲時鐘、精確 step 時間、注入測試場景、模擬玩家輸入、以 JSON 觀察遊戲狀態、截圖——全部用來驗證程式碼變更是否正確。

連線遊戲測試怎麼運作？

Open Godot MCP 可以啟動多個 Godot 實例（host + client）、模擬 peer、注入網路條件（延遲、封包遺失）、驗證遊戲狀態跨實例同步。

文件

完整文件索引見 Docs/README.md。按資料夾分類，解耦合設計。

致謝

Open Godot MCP 站在巨人的肩膀上，截優去短自以下專案：

• Coding-Solo/godot-mcp（4.8k stars）——基礎架構典範

• satelliteoflove/godot-mcp——確定性 playtesting、cheap observation、read/write 分離

• hi-godot/godot-ai——debugger channel runtime、Undo/Redo、Windows port reservation、20+ client 配置、McpTestSuite

• tomyud1/godot-mcp——雙通道架構、Variant 序列化、刪除保護

• rosskarchner/godot-mcp——DAP + LSP 整合、多實例、port isolation

• Erodenn/godot-mcp-runtime——zero-footprint、Playwright for Godot 概念

• thediymaker/godot-mcp——149 tools 的功能廣度參考

授權

MIT——100% 開源，所有功能免費，無 freemium，無付費牆。