# Godot MCP — AI Game Developer Wiki

Godot MCP 將 Claude、Cursor、Copilot 等 AI 代理連接到 Godot 編輯器。從這裡開始了解安裝、設定、工具、擴充功能與 CLI。

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/godot)。

Godot MCP 是 AI Game Developer 的 Godot 外掛。它讓 Claude Code、Cursor、GitHub Copilot、Codex 或 Gemini 等 AI 代理在 Godot 編輯器內工作：查詢與編輯場景樹、開啟並儲存 `.tscn` 場景、變更 `.tres` 資源與專案設定、讀寫 C# 與 GDScript 檔案、建置 C# 專案、在編輯器中執行 C# 程式碼片段，以及擷取模型能查看的螢幕截圖。本 wiki 說明如何安裝、連接 AI 用戶端，以及日常使用方式。

## Godot MCP 是什麼

Godot MCP 是一個 C# 編輯器外掛（資料夾 `addons/godot_mcp/`，在 Project Settings 中顯示為 **Godot-MCP**），執行於 Godot 4 .NET 專案中。當編輯器載入它時，外掛會開啟一個名為 **AI Game Developer** 的停駐面板，並連線到 MCP 伺服器。與你對話的 AI 代理會連線到同一個伺服器，並透過 Model Context Protocol（MCP）呼叫此外掛的工具。

此外掛為開放原始碼（Apache-2.0），位於 [Godot-MCP repository](https://github.com/IvanMurzak/Godot-MCP)。它與 Unity MCP、Unreal MCP 共用 MCP 與反射函式庫，因此三個引擎外掛的行為一致，並使用同一個雲端帳號。

## 各部分如何協同運作

| 元件 | 功能 |
| --- | --- |
| Godot MCP 外掛 | 在 Godot 編輯器中執行，提供 AI 工具並連線到 MCP 伺服器。 |
| MCP 伺服器 | 位於 [ai-game.dev](https://ai-game.dev) 的雲端伺服器（預設），或是在你自己機器上執行的自架伺服器。 |
| AI 用戶端 | Claude Code、Cursor、VS Code Copilot、Codex、Gemini 或任何其他 MCP 用戶端。它會連線到同一個伺服器。 |
| `godot-cli` | npm 命令列工具，可安裝外掛、登入帳號、寫入 AI 用戶端設定並開啟編輯器。 |
| AI Game Dev 應用程式 | 桌面應用程式，不需終端機就能為你安裝外掛並開啟編輯器。 |

在預設的 Cloud 模式下，除了 Godot 與你的 AI 用戶端外，你的機器上不會執行任何其他東西：編輯器與代理都連線到託管端點，而你只需用 ai-game.dev 帳號登入一次。在 Custom 模式下，外掛可以為你下載並啟動本機 MCP 伺服器，讓一切留在你的電腦上。

## 需求一覽

- **Godot 4.3 或更新版本的 .NET（mono）組建**。僅支援 GDScript 的標準組建無法編譯此外掛。
- **.NET 8 SDK**。
- 含有 C# `.csproj` 的 Godot 專案。你自己的遊戲程式碼仍可以是 GDScript；外掛只需要 C# 專案來編譯自身。
- 支援 MCP 的 AI 用戶端。

完整清單（包含你的 `.csproj` 所需的 NuGet 套件）請見 [Installation](https://ai-game.dev/zh-hant/docs/wiki/godot/installation)。

## 快速開始

如果你熟悉終端機，以下指令可以讓一個 Godot C# 專案從零到連接 AI 代理：

```bash
npm install -g godot-cli
godot-cli install-plugin ./MyGodotProject
godot-cli login
godot-cli setup-mcp claude-code ./MyGodotProject
godot-cli open ./MyGodotProject
```

接著向你的代理提出類似「新增一個含有 Camera3D 與 MeshInstance3D 立方體的 Node3D 場景，然後存成 Main.tscn」的要求。[Getting started](https://ai-game.dev/zh-hant/docs/wiki/godot/getting-started) 頁面會逐步說明相同步驟並附上解釋，而本站的 [quickstart](https://ai-game.dev/zh-hant/docs/quickstart) 則涵蓋三個引擎。

## 本 wiki 的頁面

- [Installation](https://ai-game.dev/zh-hant/docs/wiki/godot/installation)：所有安裝方式（桌面應用程式、`godot-cli`、Asset Library、發行版 zip）以及所需的確切 NuGet 套件。
- [Getting started](https://ai-game.dev/zh-hant/docs/wiki/godot/getting-started)：首次連線、第一次下指令，以及如何確認一切正常運作。
- [Connecting AI clients](https://ai-game.dev/zh-hant/docs/wiki/godot/connecting-ai-clients)：Cloud 端點與自架伺服器的差異、裝置登入、專案金鑰，以及各代理的 `setup-mcp`。
- [Configuration](https://ai-game.dev/zh-hant/docs/wiki/godot/configuration)：AI Game Developer 面板、已儲存的設定，以及 `GODOT_MCP_*` 環境變數。
- [Tools](https://ai-game.dev/zh-hant/docs/wiki/godot/tools)：內建工具家族、RQL，以及各工具的用途。
- [Custom tools](https://ai-game.dev/zh-hant/docs/wiki/godot/custom-tools)：用 C# 撰寫自己的 MCP 工具，並從執行中的遊戲提供工具。
- [Extensions](https://ai-game.dev/zh-hant/docs/wiki/godot/extensions)：動畫、CSG、導覽、圖磚地圖與熱門 Godot 外掛的選用套件。
- [godot-cli reference](https://ai-game.dev/zh-hant/docs/wiki/godot/cli)：所有 `godot-cli` 指令與其旗標。
- [Troubleshooting](https://ai-game.dev/zh-hant/docs/wiki/godot/troubleshooting)：外掛無法載入、代理看不到工具、重新載入問題。
- [FAQ](https://ai-game.dev/zh-hant/docs/wiki/godot/faq)：常見問題的簡短解答。

## 網站上的更多內容

- [Install Godot MCP](https://ai-game.dev/zh-hant/engines/godot)：Godot 安裝頁面。
- [Godot tools catalog](https://ai-game.dev/docs/tools/godot) 與 [Godot extensions](https://ai-game.dev/docs/extensions/godot)。
- [Godot 最佳實務](https://ai-game.dev/docs/best-practices/godot)：如何撰寫效果良好的提示詞。
- [MCP 端點](https://ai-game.dev/zh-hant/mcp-endpoint-info)與[驗證](https://ai-game.dev/docs/auth)：託管端點與登入的運作方式。
- [AI Game Dev 應用程式 wiki](https://ai-game.dev/zh-hant/docs/wiki/app)，以及 [Unity MCP](https://ai-game.dev/zh-hant/docs/wiki/unity) 和 [Unreal MCP](https://ai-game.dev/zh-hant/docs/wiki/unreal) 的 wiki。

- [**安裝** 使用 AI Game Dev 應用程式、godot-cli、Godot Asset Library 或 release zip 安裝 Godot MCP 附加元件，並為你的 .csproj 加上正確的 NuGet 套件。](https://ai-game.dev/zh-hant/docs/wiki/godot/installation)
- [**開始使用** 將 Godot MCP 連上雲端、接好 Claude Code 等 AI agent、確認連線，並在 Godot 編輯器中執行你的第一批 AI 提示。](https://ai-game.dev/zh-hant/docs/wiki/godot/getting-started)
- [**連接 AI 用戶端** 透過 ai-game.dev 雲端端點或你自己的本機伺服器，將 Claude Code、Cursor、Copilot、Codex、Gemini 及其他 MCP 用戶端連線到 Godot MCP。](https://ai-game.dev/zh-hant/docs/wiki/godot/connecting-ai-clients)
- [**設定** 在 AI Game Developer 面板中設定 Godot MCP、選擇 AI 代理可看到的工具，並用 GODOT\_MCP\_\* 環境變數覆寫設定。](https://ai-game.dev/zh-hant/docs/wiki/godot/configuration)
- [**工具** AI 代理在 Godot 編輯器中使用的 Godot MCP 工具：以 RQL 查詢節點、場景與資源，處理 C# 與 GDScript 腳本、螢幕擷取與遊戲內工具。](https://ai-game.dev/zh-hant/docs/wiki/godot/tools)
- [**自訂工具** 用 C# 撰寫你自己的 Godot MCP 工具，在主執行緒上呼叫 Godot API，並從執行中的 Godot 遊戲對外提供工具、提示詞與資源。](https://ai-game.dev/zh-hant/docs/wiki/godot/custom-tools)
- [**擴充套件** 安裝選用的 Godot MCP 擴充套件，涵蓋 AnimationPlayer、CSG、GridMap、導覽、粒子、TileMapLayer、Beehave、Dialogic、Phantom Camera 與 Terrain3D。](https://ai-game.dev/zh-hant/docs/wiki/godot/extensions)
- [**godot-cli 參考** Godot MCP 的每個 godot-cli 指令與旗標，從 install-plugin、login、setup-mcp 到 open、exec、run-tool、configure 與 install-extension。](https://ai-game.dev/zh-hant/docs/wiki/godot/cli)
- [**疑難排解** 解決常見的 Godot MCP 問題，從附加元件無法載入或編譯、Extensions 清單空白、工具遺失、重新載入錯誤，到 .NET 10 當機。](https://ai-game.dev/zh-hant/docs/wiki/godot/troubleshooting)
- [**常見問題** 關於 Godot 編輯器 AI 助理 Godot MCP 的簡短解答：Godot 版本、GDScript 專案、離線使用、費用、安全性與匯出的遊戲。](https://ai-game.dev/zh-hant/docs/wiki/godot/faq)

---

Source (HTML): https://ai-game.dev/zh-hant/docs/wiki/godot

Machine-translated (zh-Hant) from the English page: https://ai-game.dev/docs/wiki/godot