Open Godot MCP

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

License: MIT Godot 4.5+ Python 3.11+ MCP

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。

屬性	值
專案類型	MCP server（Model Context Protocol）for Godot Engine
目標引擎	Godot 4.5+（GDScript + C# 支援）
執行環境	Python 3.11+（server）+ GDScript（addon）
授權	MIT（100% 開源，無 freemium）
工具數	~35 MCP tools（含 5 個動態註冊的 Agnes/NVIDIA AI 工具），~130 actions
核心功能	確定性 playtesting、連線測試、DAP 除錯、LSP、Token 效率、Agnes/NVIDIA AI API 整合
AI 客戶端	Claude Desktop、Cursor、Windsurf、VS Code（MCP）、Continue、Zed、任何 MCP 相容客戶端
平台	Windows、macOS、Linux
獨有能力	連線遊戲測試（其他 Godot MCP 都沒有）、DAP + LSP 整合

---

為什麼要做這個

市面上的 Godot MCP 都有缺陷：

問題	現有 MCP	Open Godot MCP
AI 看不到遊戲實際運行	只能編輯，不能玩遊戲修 BUG	確定性 playtesting——freeze 時鐘、step 精確時間、step_until 條件
連線不穩	硬編碼 port、無心跳、WSL2 衝突	可配置 port + 心跳 + 智慧重連 + port 自動避讓
無法測連線遊戲	所有 MCP 都缺 multiplayer 測試	獨有——多實例、peer 模擬、同步驗證、網路條件注入
Token 浪費	完整回傳、PNG 無壓縮、無 diff	cheap observation、截圖壓縮、diff、摘要、增量查詢
免費版閹割	freemium，功能要付費	100% MIT 開源，所有功能免費

---

適合誰用？

• Godot 4 遊戲開發者——想讓 AI 幫忙寫程式、測試、除錯
• AI 輔助程式設計師（Claude、Cursor、Windsurf、VS Code MCP 使用者）——在 Godot 專案上工作
• 獨立遊戲工作室——需要自動化 playtesting，不想自己寫測試框架
• 連線遊戲開發者——需要測試網路同步、延遲、peer 行為
• 開源倡議者——想要完全免費、無付費牆的 MCP server

---

使用情境

情境	Open Godot MCP 如何幫助
AI 修移動 bug	AI 設斷點 → 運行遊戲 → 檢查變數 → 找到根因 → 修程式 → 重測
自動化 Boss 戰測試	凍結時鐘 → 生成 Boss → step 時間 → 模擬閃避輸入 → 驗證玩家存活
連線同步驗證	啟動 host + client 實例 → 注入延遲 → 比較同步狀態 → 偵測 desync bug
效能分析	拍 profiler 快照 → 找 spike → 最佳化 → 重新測量
回歸測試	程式碼變更後跑測試套件 → 斷言遊戲狀態符合預期
關卡設計迭代	AI 建立節點 → 排列場景 → 運行遊戲 → 截圖 → 調整

---

核心能力

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 自動重試。

工具	來源	功能	費用
agnes_vision	Agnes 2.0 Flash	圖像理解（URL-only，本地檔自動上傳 uguu.se）	免費
agnes_image_generate	Agnes Image 2.0 Flash	文生圖 / 圖生圖	免費
agnes_video_generate	Agnes Video V2.0	產影片（非同步任務）	免費
nvidia_vision	NVIDIA NIM VLM	圖像理解（base64 直傳，免上傳）	免費
nvidia_image_generate	NVIDIA FLUX.2-klein-4b	文生圖	免費

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 分離設計。

領域	工具	說明
編輯器	godot_editor_read/edit	狀態、場景、選取
場景	godot_scene	建立、讀取、儲存
節點	godot_node_read/edit	CRUD、屬性、群組、signal
腳本	godot_script	diff 編輯、驗證
專案	godot_project	設定、autoload
輸入映射	godot_input_map	InputMap 管理
資源	godot_resource	型別感知檢視
動畫	godot_animation	建立、軌道、預設
TileMapLayer	godot_tilemap	cell 讀寫
遊戲控制	godot_game	play/stop/freeze
時鐘	godot_game_time	freeze/step/step_until
輸入	godot_input	鍵盤/滑鼠/手把/文字
狀態	godot_runtime_state	digest/watch/signals
注入	godot_exec	eval/call/assert
截圖	godot_screenshot	壓縮、存檔、自動清理
除錯	godot_debugger	DAP breakpoint、stack_trace、variables、evaluate
程式碼	godot_lsp	診斷、完成
效能	godot_profiler	快照、時序
測試	godot_test	框架、執行
連線	godot_network	多實例、同步、網路條件
實例	godot_instance	多 Godot 管理
檔案	godot_filesystem	讀寫、搜尋
文件	godot_docs	版本對應
日誌	godot_log	增量查詢
批次	godot_batch	一次多操作
資產	godot_asset	生成、管理
匯出	godot_export	預設、匯出
健康	godot_health	連線檢查
Agnes 視覺	agnes_vision	圖像理解（動態註冊）
Agnes 產圖	agnes_image_generate	文生圖/圖生圖（動態註冊）
Agnes 產影片	agnes_video_generate	非同步影片生成（動態註冊）
NVIDIA 視覺	nvidia_vision	VLM 圖像理解（動態註冊）
NVIDIA 產圖	nvidia_image_generate	FLUX 文生圖（動態註冊）

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

---

與現有 Godot MCP 比較

特性	godot-ai	godot-mcp	Coding-Solo	satelliteoflove	thediymaker	Open Godot MCP
編輯器操作	✅	✅	✅	✅	✅ 149 tools	✅
真實遊戲操作	⚠️	⚠️	❌	✅ 確定性	⚠️	✅ 確定性+即時
連線遊戲測試	❌	❌	❌	❌	❌	✅ 獨有
DAP 除錯	❌	❌	❌	❌	❌	✅
LSP 整合	❌	❌	❌	❌	❌	✅
Token 效率	⚠️	⚠️	❌	✅	❌	✅ 全面
連線穩定	⚠️	❌	—	✅	—	✅ 最穩
授權	開源	開源	MIT	MIT	MIT	MIT

---

常見問題

什麼是 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。按資料夾分類，解耦合設計。

資料夾	內容
Docs/00-Overview/	功能概觀、設計理念
Docs/01-Architecture/	架構、通訊協議、連線穩定、多實例、runtime
Docs/02-Tools/	完整工具清單（按領域獨立檔案）
Docs/03-Realtime-Testing/	確定性 playtesting（Guide + Examples）
Docs/04-Token-Efficiency/	省 token 設計（Guide + Strategies）
Docs/05-Network-Testing/	連線遊戲測試（Guide + Examples）
Docs/06-Installation/	安裝（Guide + Troubleshooting）
Docs/07-Roadmap/	開發路線圖
Docs/08-CSharp-Support/	C# Godot 相容性與語法檢查
Docs/09-Research/	現有 MCP 調研、C# MCP 調研

---

致謝

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，無付費牆。