本頁面由英文機器翻譯而成。閱讀英文原文。

開始使用

將 Godot MCP 連上雲端、接好 Claude Code 等 AI agent、確認連線，並在 Godot 編輯器中執行你的第一批 AI 提示。

更新於 2026年11月4日 以 Markdown 檢視

本頁帶你從已安裝的 addon 一路走到能編輯 Godot 場景的 AI agent。這裡假設 addon 已經在你的專案裡；如果還沒，請先從 Installation 開始。以下步驟採用預設的 Cloud 模式，編輯器與你的 agent 都會連到 ai-game.dev，你只需登入一次。

步驟 1：開啟專案

用 CLI 開啟專案：

godot-cli open ./MyGodotProject

open 會先建置 C# 組件，然後才啟動編輯器。首次開啟時這個建置很重要：Godot 會立刻載入已啟用的 addon，若沒有建置好的組件，它會回報無法載入 GodotMcpPlugin.cs 並停用該 addon。如果你改從 Godot 專案管理員開啟專案，請先建置一次（編輯器的 Build 按鈕或 godot-cli build），並在 Godot 把外掛關掉時重新啟用它。

addon 載入後，編輯器的 Output 面板會印出 [Godot-MCP] plugin loaded，且右上角的 dock 區域會出現 AI Game Developer 面板。

步驟 2：登入

Cloud 模式需要你的 ai-game.dev 帳號。以下方式任選一種：

  • 在 dock 中讓模式保持在 Cloud，然後點擊 Authorize。瀏覽器會開啟並顯示一組簡短代碼；用你的 ai-game.dev 帳號核准即可。
  • 從終端機執行 godot-cli login。它使用相同的 OAuth 裝置流程，並把憑證存到 ~/.ai-game-dev/credentials.json，編輯器會自行讀取。

每台機器只需登入一次。同一份憑證可供 Godot MCP、Unity MCP、Unreal MCP、各引擎 CLI 以及 AI Game Dev 應用程式使用。這個工作階段會出現在你帳號的已連結裝置中，你可以在那裡撤銷它。詳情請見：Authentication。

步驟 3：連接你的 AI agent

為你使用的 agent 撰寫 MCP 設定。以 Claude Code 為例：

godot-cli setup-mcp claude-code ./MyGodotProject

這會在專案中寫入 .mcp.json，其中的 URL 固定指向這個專案，因此即使你同時開了好幾個編輯器，agent 也能連到這個編輯器。你也可以在 dock 中做同樣的事：在 AI agent 區塊選擇你的 agent，然後點擊 Configure。其他 agent（Cursor、VS Code Copilot、Codex、Gemini 等）列在 Connecting AI clients。

設定寫好之後，請重新啟動 agent，或重新載入它的 MCP 伺服器。若設定檔放在專案資料夾中，請從該專案資料夾啟動 agent（Claude Code 會從它啟動所在的資料夾讀取 .mcp.json）。

步驟 4：確認連線

dock 的 Connection 區塊會顯示三個點組成的一列：Godot、MCP 伺服器與 AI agent。當編輯器已連線且有 agent 工作階段進行中時，三個點都會亮起，且 agent 那一列會顯示用戶端名稱。你也可以從終端機等待編輯器回應：

godot-cli wait-for-ready ./MyGodotProject
godot-cli status ./MyGodotProject

wait-for-ready 會持續輪詢就緒探測（ping）直到它回應，預設最多等待兩分鐘。status 會回報該專案是否有編輯器正在執行，以及伺服器是否有回應。

在你的 agent 中，請它列出可用的工具，或在 Claude Code 中執行 /mcp。你應該會看到 rql-query、rql-mutate、script-create 和 screenshot-viewport 等工具。

步驟 5：第一批提示

在你的 agent 聊天室中試試以下提示。每一個都對應到真實工具，因此你可以在編輯器中看著場景改變：

  • 「新增一個含有 Camera3D 與 MeshInstance3D 立方體的 Node3D 場景，然後存成 Main.tscn。」
  • 「以半徑 2 圍成一圈建立 3 個立方體。」
  • 「列出場景中所有的 OmniLight3D 及其 energy。」
  • 「為地板建立一個 StandardMaterial3D，並把它的 albedo 顏色設為灰色。」
  • 「建立一個含有 public float Speed 的 Player.cs 腳本，將它掛到 Player 節點上並建置專案。」
  • 「新增一個名為 jump 的輸入動作，綁定 Space 鍵。」
  • 「擷取 viewport 的螢幕截圖，並告訴我你看到什麼。」

agent 所做的場景編輯都可以復原：在編輯器按 Ctrl+Z 就能逐步退回，跟你自己的編輯完全一樣。場景變更會把場景標記為未儲存，所以請 agent 儲存，或自己儲存。更多提示靈感請見 Best practices for Godot。

agent 看得見與看不見什麼

agent 是透過 addon 提供的工具來工作。它可以經由 RQL 讀取場景樹、Godot 屬性（包含 GDScript 變數）、資源、檔案、專案設定、輸入對應、autoload、主控台與編輯器狀態，也可以查看螢幕截圖。它無法在編輯器 UI 中點擊。完整清單請見 Tools 與 Godot tools catalog。

想完全離線使用嗎？

你可以改用在自己的電腦上執行 MCP 伺服器，而不透過雲端。在 dock 中將模式切換為 Custom 並點擊 Start Server：外掛會從 GitHub 下載對應的伺服器版本、啟動並連線。接著讓你的代理指向本機 URL。請參閱 Connecting AI clients。

後續步驟

  • Configuration：dock、日誌等級，以及代理能看到哪些工具。
  • Extensions：新增 AnimationPlayer、CSG、導覽、tilemap 與外掛支援。
  • Troubleshooting：當上述步驟無法運作時。