# 連接 AI 用戶端 — Godot · AI Game Developer Wiki

透過 ai-game.dev 雲端端點或你自己的本機伺服器，將 Claude Code、Cursor、Copilot、Codex、Gemini 及其他 MCP 用戶端連線到 Godot MCP。

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

Godot MCP 有兩個部分，兩者都會連線到 MCP 伺服器：Godot 編輯器中的外掛，以及你與之對話的 AI 用戶端。本頁說明兩種連線模式、登入的運作方式，以及如何用 `godot-cli setup-mcp` 或停靠面板上的 **Configure** 按鈕，為每個支援的代理撰寫 MCP 設定。

## Cloud 模式（預設）

在 Cloud 模式下，外掛會連線到 `https://ai-game.dev` 的託管後端，而你的 AI 用戶端則連線到 MCP 端點 `https://ai-game.dev/mcp`。你的機器上不會額外執行任何東西，而且能跨越防火牆運作。這是預設模式，也是我們對大多數人的建議。

### 使用裝置流程登入

Cloud 驗證採用 OAuth 2.1 裝置授權流程。你完全不需要手動複製權杖：

```bash
godot-cli login
```

CLI 會印出一組短代碼、開啟瀏覽器，並等待你核准。憑證（存取權杖、會輪替的重新整理權杖與到期時間）會儲存到機器儲存區 `~/.ai-game-dev/credentials.json`（macOS 與 Linux 上檔案模式為 0600，Windows 上受 DPAPI 保護）。編輯器外掛、其他引擎 CLI 與 AI Game Dev 應用程式都會取用它，過期的存取權杖也會自動重新整理。在停靠面板中點選 **Authorize** 會在 Godot 內執行相同的流程。

實用的 `login` 旗標：`--force` 會在已有憑證的情況下重新登入，`--project <path>` 會保留一份獨立的各專案憑證，而 `--tools-only` 會為 CI runner 建立範圍較窄的憑證。請參閱 [godot-cli 參考文件](https://ai-game.dev/zh-hant/docs/wiki/godot/cli#login) 與 [驗證](https://ai-game.dev/docs/auth)。

### 固定的專案 URL

純端點 `https://ai-game.dev/mcp` 會把你的代理路由到你其中一個已連線的編輯器。同時開啟多個專案時這會有歧義，因此 `setup-mcp` 預設會寫入固定 URL：`https://ai-game.dev/mcp/p/<pin>`，其中 pin 由專案衍生而來。以此設定啟動的代理一定連得到這個專案的編輯器。若想要純 URL，請傳入 `--no-pin`。

### 專案金鑰

當你登入後，`setup-mcp` 會把專案金鑰寫入代理設定，形式為 `Authorization: Bearer agd_pk_…`。專案金鑰不會過期，且只能用於此專案的 pin，因此無法存取你帳號下的其他專案。每個專案只會建立一次，並從 `~/.ai-game-dev/project-keys.json` 重複使用。

- `--regenerate-key` 會建立新金鑰、改寫設定並撤銷舊金鑰。
- `--oauth` 則改為寫入僅含 URL 的設定：由代理以自己的 OAuth 提示登入。
- 若機器上沒有登入，設定也會是僅含 URL 的形式。

**警告**

專案金鑰就是一種憑證。請勿把含有金鑰的設定檔（例如 `.mcp.json` 或 `.cursor/mcp.json`）提交到公開的儲存庫。

## 自訂模式：你自己的伺服器

在自訂模式下，外掛會連線到你選擇的伺服器 URL，例如你自己機器上的伺服器。該伺服器是開源的 [GameDev-MCP-Server](https://github.com/IvanMurzak/GameDev-MCP-Server)，與 Unity MCP 和 Unreal MCP 使用的是同一個二進位檔。

最簡單的方式是讓外掛來執行它：

1. 在停靠面板中，把模式切換為 **Custom**。
2. 讓 **Server URL** 保持為 `http://localhost:8080`，或輸入另一個本機 URL。
3. 點選 **Start Server**。外掛會從 GitHub（僅限 HTTPS、github.com）下載其固定伺服器版本的伺服器建置檔，快取到 `.godot/mcp-server/<platform>/`，啟動它並連線。

**Stop Server** 會停止它，關閉編輯器也會停止。在 CI 環境中會略過下載。若想自行執行伺服器，可下載發行版二進位檔或 `aigamedeveloper/mcp-server` Docker 映像檔：

```bash
./gamedev-mcp-server --client-transport streamableHttp --port 8080
```

### 自訂伺服器的授權

自訂模式有一個 **Authorization Token** 開關，共三種值：

| 值 | 意義 |
| --- | --- |
| `none` | 不驗證。適用於只在自己機器上監聽的伺服器。 |
| `oauth` | 傳送你已登入的 ai-game.dev 帳號權杖，但僅限於 localhost 伺服器（`localhost`、`127.0.0.0/8`、`::1`）。 |
| `token` | Bearer 權杖。點選 **New** 產生一個；它會以遮蔽方式儲存。 |

對於任何非本機主機搭配 `oauth`，外掛會拒絕傳送你的帳號權杖；請改為設定 `GODOT_MCP_TOKEN`。兩種模式的環境變數都列在 [組態設定](https://ai-game.dev/zh-hant/docs/wiki/godot/configuration#environment-variables)。

若要讓代理指向本機伺服器，請把 URL 傳給 `setup-mcp`：

```bash
godot-cli setup-mcp claude-code ./MyGodotProject --url http://localhost:8080
```

本機伺服器設定永遠不會帶有專案金鑰。

## 支援的代理與設定檔

執行 `godot-cli setup-mcp --list` 可查看每個 agent id。以下是目前 CLI 所知道的所有 id，以及它寫入設定的位置：

| Agent | id | 設定檔 |
| --- | --- | --- |
| Claude Code | `claude-code` | 專案中的 `.mcp.json` |
| Claude Desktop | `claude-desktop` | 使用 Claude 自訂連接器（見下文） |
| Cursor | `cursor` | `.cursor/mcp.json` |
| Visual Studio Code (Copilot) | `vscode-copilot` | `.vscode/mcp.json` |
| Visual Studio (Copilot) | `vs-copilot` | `.vs/mcp.json` |
| Rider (Junie) | `rider-junie` | `.junie/mcp/mcp.json` |
| GitHub Copilot CLI | `github-copilot-cli` | `~/.copilot/mcp-config.json` |
| Gemini | `gemini` | `.gemini/settings.json` |
| Antigravity | `antigravity` | `~/.gemini/config/mcp_config.json` 與 `~/.gemini/antigravity/mcp_config.json` |
| Cline | `cline` | VS Code 全域儲存空間中的 `cline_mcp_settings.json` |
| Open Code | `open-code` | `opencode.json` |
| Codex | `codex` | `.codex/config.toml` |
| Kilo Code | `kilo-code` | `.kilocode/mcp.json` |
| 任何其他 MCP 用戶端 | `custom` | 專案中的 `mcp.json` |

範例：

```bash
godot-cli setup-mcp cursor ./MyGodotProject
godot-cli setup-mcp codex ./MyGodotProject
godot-cli setup-mcp vscode-copilot ./MyGodotProject --oauth
```

每個設定都使用 HTTP 傳輸（`type: http` 與一個 URL）。Codex 則是把金鑰放進 `http_headers`。

### Claude Desktop 與 claude.ai

Claude Desktop 不會從 `claude_desktop_config.json` 接受 HTTP 伺服器項目。Claude Desktop 與 claude.ai 改為以 Claude 自訂連接器的方式連上雲端端點：在 Claude 的設定中新增自訂連接器、貼上專案固定的雲端 URL，並以你的 ai-game.dev 帳號登入。Claude Desktop 無法使用 Custom 模式的伺服器，因為 Godot MCP 並未為它提供 stdio 傳輸。若要使用本機伺服器，請改用表中支援 HTTP 的 agent，例如 Claude Code。

## 從 dock 面板設定

dock 的 **AI agent** 區塊功能等同於 `setup-mcp`：從清單中選擇你的 agent，然後點選 **Configure**（或 **Reconfigure**）。狀態列會顯示該 agent 的設定檔是否已設定完成；若你在設定後變更伺服器 URL、模式或授權，就會出現 **Reconfiguration Required** 提示。**Remove** 會從該 agent 的設定中刪除 Godot MCP 項目。

## 你的 agent 適用的 Skills

有些 agent 會讀取 skill 檔案（`SKILL.md`），從中學習如何使用這些工具。dock 的 AI agent 區塊中的 **Skills** 列可以產生這些檔案（**Generate**，或 **Auto-generate** 開關）。從終端機執行：

```bash
godot-cli setup-skills claude-code ./MyGodotProject
```

這會在沒有執行編輯器的情況下，把檔案寫入該 agent 的 skills 資料夾，例如 Claude Code 的 `.claude/skills`。`setup-skills --list` 會顯示哪些 agent 支援 skills。

## 可直接複製貼上的設定

如果你的用戶端不在清單中，任何支援 HTTP 伺服器的 MCP 用戶端都能使用：將它指向 `https://ai-game.dev/mcp`（或固定的 URL），讓它以 OAuth 登入，或加入 bearer 標頭。許多用戶端的現成片段可在 [MCP 端點頁面](https://ai-game.dev/zh-hant/mcp-endpoint-info) 找到。

---

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

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