godot-mcp

📚 Godot MCP 項目介紹

一、項目概述

Godot MCP（Model Context Protocol 伺服器）由 Coding‑Solo 發布，是一款橋接 AI 助手與 Godot 引擎的工具。透過 MCP 協議，它可以啟動 Godot 編輯器、運行項目、捕獲除錯資訊，並對項目結構和場景進行深度控制。

這一機制為 AI 助手（如 Claude、Cline、Cursor）提供真實的回饋迴圈，使其能夠實際操作項目、除錯問題並生成高品質 GDScript 代碼。

---

二、核心功能與特性

1. 啟動編輯器與運行項目
   支持透過命令行方式：

   • 啟動指定路徑下的 Godot 編輯器
   • 以除錯模式運行項目
   • 捕獲並返回控制台輸出或錯誤訊息

2. 項目結構獲取與分析

   • 獲取項目版本、目錄結構和資源列表
   • 深入場景結構資訊，包括節點樹、屬性、資源路徑等

3. 場景與節點管理

   • 創建新場景（指定根節點類型）
   • 向現有場景添加節點並設置屬性
   • 加載 Sprite2D 紋理、導出 MeshLibrary 用於 GridMap
   • 保存場景並支持生成場景變種

4. 除錯與版本管理

   • 停止正在運行的項目
   • 獲取並顯示 Godot 引擎版本
   • （適用於 Godot 4.4+）獲取檔案 UID 並更新資源引用

5. 兼容多種 AI 輔助工具

   • 支持 Cline 和 Cursor：透過 MCP 設置檔案、命令行集成 AI 助手工具

---

三、架構與實現亮點

• 單一 GDScript “操作腳本”
  所有複雜命令（如創建節點、場景導出等）由一個 godot_operations.gd 管理，避免逐個臨時腳本生成，保證簡潔高效，並減少磁碟 I/O 與出錯可能。

• CLI 與 Script 結合機制
  簡單命令直接透過 Godot CLI，複雜操作透過 GDScript 腳本，均由 MCP 標準傳輸 JSON 指令，結構統一，易擴展。

• 標準化響應結構
  所有操作返回統一格式：狀態、結果內容、標準輸出/錯誤，從而方便 AI 分析、學習與自動生成改動建議。

---

四、使用流程

1. 安裝與構建

   git clone https://github.com/Coding-Solo/godot-mcp.git
   cd godot-mcp
   npm install
   npm run build
   

2. 配置 AI 工具

   • Cline：在 cline_mcp_settings.json 中添加對應 server 配置
   • Cursor：透過 Settings → Features → MCP 添加 node 指令

3. 運行與交互

   • AI 指令示例：

     • launch_editor：啟動編輯器
     • run_project：執行項目並獲取輸出
     • create_scene / add_node：創建場景/節點
     • get_debug_output / stop_project：除錯控制類指令
     • get_uid / update_project_uids：UID 管理

---

五、項目亮點總結

優勢	描述
🌟 高自動化	AI 助手直接操控編輯器/項目，無需手動干預
🚫 無臨時檔案	使用 GDScript 單一入口，輕量高效
♻️ 支持版本 & UID	兼容 Godot 4.4+ 特性，能管理資源 UID
🛠️ 易擴展 & 易集成	MCP 標準便於新增功能，與多 AI 工具兼容

---

六、總結 🌈

Godot MCP 是一款強大且實用的工具，它為 AI 助手與 Godot 引擎搭建了一座橋樑。AI 可直接：

• 啟動編輯器、運行項目、數據採集；
• 訪問項目結構、腳本、場景、資源；
• 動態修改場景、節點、腳本；
• 進行除錯、生成 GDScript 代碼建議。

借助統一協議與 GDScript 操作腳本，它提供了清晰、標準、可擴展的自動化介面，對遊戲開發者而言，是提升效率與智能化研發流程的利器。