# 连接 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** 按钮为每个受支持的 agent 编写 MCP 配置。

## 云端模式（默认）

在云端模式下，插件连接到 `https://ai-game.dev` 上托管的后端，你的 AI 客户端连接到 MCP 端点 `https://ai-game.dev/mcp`。你的机器上无需额外运行任何东西，而且可以跨越防火墙工作。这是默认模式，也是我们推荐给大多数人的模式。

### 使用设备流程登录

云端身份验证使用 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 运行器创建范围更窄的凭据。参见 [godot-cli 参考](https://ai-game.dev/zh-hans/docs/wiki/godot/cli#login) 和 [身份验证](https://ai-game.dev/docs/auth)。

### 固定项目 URL

普通端点 `https://ai-game.dev/mcp` 会把你的 agent 路由到你连接的某个编辑器。当同时打开多个项目时这会有歧义，因此 `setup-mcp` 默认写入固定 URL：`https://ai-game.dev/mcp/p/<pin>`，其中的 pin 由项目派生而来。用该配置启动的 agent 总能到达此项目的编辑器。如果你想要普通 URL，请传入 `--no-pin`。

### 项目密钥

登录后，`setup-mcp` 会把项目密钥以 `Authorization: Bearer agd_pk_…` 的形式写入 agent 配置。项目密钥不会过期，且仅对本项目的 pin 有效，因此无法访问你账户下的其他项目。每个项目只创建一次，并从 `~/.ai-game-dev/project-keys.json` 复用。

- `--regenerate-key` 创建一个新密钥，重写配置并撤销旧密钥。
- `--oauth` 改为写入仅含 URL 的配置：agent 用自己的 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-hans/docs/wiki/godot/configuration#environment-variables) 中。

要让 agent 指向本地服务器，请把 URL 传给 `setup-mcp`：

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

本地服务器配置从不携带项目密钥。

## 受支持的 agent 和配置文件

运行 `godot-cli setup-mcp --list` 可以查看所有 agent id。这些就是当前 CLI 已知的 id，以及它写入配置的位置：

| 智能体 | 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 的智能体，例如 Claude Code。

## 从停靠面板进行配置

停靠面板中的 **AI agent** 部分与 `setup-mcp` 作用相同：从列表中选择你的智能体，然后点击 **Configure**（或 **Reconfigure**）。状态行会说明该智能体的配置文件是否已配置好；如果在配置之后更改了服务器 URL、模式或授权信息，就会出现 **Reconfiguration Required** 提示。**Remove** 会从该智能体的配置中删除 Godot MCP 条目。

## 为你的智能体提供技能

有些智能体会读取技能文件（`SKILL.md`），这些文件教它们如何使用这些工具。AI agent 部分中的 **Skills** 行可以生成这些文件（**Generate**，或 **Auto-generate** 开关）。在终端中：

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

这会把文件写入该智能体的技能文件夹，例如 Claude Code 的 `.claude/skills`，而且无需运行编辑器。`setup-skills --list` 会显示哪些智能体支持技能。

## 可复制粘贴的配置

如果你的客户端不在列表中，任何支持 HTTP 服务器的 MCP 客户端都可以使用：将它指向 `https://ai-game.dev/mcp`（或固定 URL），让它通过 OAuth 登录，或者添加 bearer 头。许多客户端的现成片段都在 [MCP 端点页面](https://ai-game.dev/zh-hans/mcp-endpoint-info) 上。

---

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

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