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）
• 截圖自動清理：自動輪轉（預設保留最近 50 張）+ 過期淘汰（預設 24 小時）+ 手動 cleanup action，防止垃圾檔累積。v0.1.6+ 可直接在 Dock 面板調整保留數和時數（per-project）
• read/write 分離：read auto-allow，write gate
• 批次操作：一次 round-trip 完成多個操作

4. 連線穩定

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

• 可配置 port（env > EditorSettings > 自動避讓）
• Windows Port Reservation 偵測（避開 Hyper-V/WSL2/Docker 保留 port）
• 心跳機制（主動偵測死連線）
• 智慧重連（指數退避 + 最大次數 + UI 通知）

5. 行程生命週期管理（Windows 孤兒行程防護）

MCP stdio 架構下，每個 AI client session 各自啟動一個 server 行程。Windows 殺 parent 時不會關閉 child 的 inherited stdin handle，導致孤兒行程永遠活著、越積越多。

• Parent watchdog：server 啟動後每 5 秒檢查 parent 是否存活，parent 消失即自動退出
• --shutdown-all：更新前一鍵清除所有殘留行程，解鎖 .exe，不需重開電腦

# 更新前清場（殺所有殘留 server 行程）
open-godot-mcp --shutdown-all
# 再跑更新
uv sync

6. 完整除錯

• DAP（Debugger Adapter Protocol）：breakpoint、step、變數 inspect（stack_trace、variables、evaluate）
• LSP（Language Server Protocol）：靜態診斷、自動完成、go-to-definition
• Profiler：效能快照、時序分析、spike 偵測

7. Agnes / NVIDIA AI API 整合（動態註冊）

5 個 AI 工具可選啟用，預設關閉。在 dock 面板填入 API key + 勾選子功能後才動態註冊，未啟用時 AI 工具清單完全看不到。支援多 key 輪換（429/402/401 自動換 key）+ 5xx 自動重試。

Config 預設存於 ~/.open_godot_mcp/config.json（user home，不在 git repo 內）。v0.1.6+ 可在 Dock 面板勾選「使用專案級設定檔」，改存於 <專案>/.open_godot_mcp/config.json（per-project，不同專案可用不同 API key）。詳見 Docs/02-Tools/Agnes-NVIDIA.md。

快速開始

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。

工具清單

~35 tools（含 5 個動態註冊的 Agnes/NVIDIA AI 工具），~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、注入網路條件（延遲、封包遺失）、驗證遊戲狀態跨實例同步。

Agnes / NVIDIA AI 工具是什麼？

5 個可選啟用的 AI 工具（視覺、產圖、產影片），整合 Agnes AI API 和 NVIDIA NIM API。預設關閉，需在 dock 面板填入 API key + 勾選子功能後才動態註冊。支援多 key 輪換和 5xx 自動重試。兩家 API 都有免費額度。詳見 Docs/02-Tools/Agnes-NVIDIA.md。

安全須知

Open Godot MCP 讓 AI 在 Godot 編輯器和遊戲執行時內操作，以下是安全相關資訊：

網路暴露範圍

所有 WebSocket 連線綁定 127.0.0.1（localhost only），不暴露到 LAN/WAN。Bridge 支援 auth_token 認證（在 Godot EditorSettings 設定 open_godot_mcp/security/auth_token），未設定 token 時接受所有本機連線。

API Key 安全

Agnes / NVIDIA API key 存於 ~/.open_godot_mcp/config.json（user home，不在 git repo 內）。檔案權限設為 0o600（POSIX，僅 owner 可讀寫）。.gitignore 全域排除 **/config.json，防止意外提交。若使用專案級設定檔，內建 git safety check 會偵測 config 是否在 git repo 內並警告。

godot_exec eval 風險

godot_exec eval 允許 AI 在運行中的遊戲執行任意 GDScript。這是確定性 playtesting 的必要功能（AI 需要設定測試場景、呼叫方法、斷言條件）。GDScript 受 Godot sandbox 限制，但仍可存取檔案系統和網路。

如果不需要 eval，可用 --no-eval 關閉：

open-godot-mcp --no-eval

安全加固選項

# 關閉 eval（禁止 AI 執行任意 GDScript）
open-godot-mcp --no-eval

# 唯讀模式（禁止所有寫入操作）
open-godot-mcp --read-only

# 限制檔案存取範圍（只允許存取指定目錄）
open-godot-mcp --allowed-paths /path/to/project

# 同時使用三層防護
open-godot-mcp --no-eval --read-only --allowed-paths /path/to/project

Prompt Injection 注意事項

AI 可能被 prompt injection 攻擊（例如遊戲內文字、網頁內容、使用者輸入中藏惡意指令）。建議：

• 在生產環境使用 --no-eval + --allowed-paths
• 不要在公開網路環境中開放 Bridge 連線
• 定期檢查 ~/.open_godot_mcp/config.json 的 API key 是否外洩

文件

完整文件索引見 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，無付費牆。