# 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 仓库](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 包）见 [安装](https://ai-game.dev/zh-hans/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”的指令。[入门](https://ai-game.dev/zh-hans/docs/wiki/godot/getting-started) 页面会附带说明逐步讲解相同的步骤，本站的 [快速开始](https://ai-game.dev/zh-hans/docs/quickstart) 则涵盖全部三个引擎。

## 本 wiki 的页面

- [安装](https://ai-game.dev/zh-hans/docs/wiki/godot/installation)：所有安装方式（桌面应用、`godot-cli`、Asset Library、发布压缩包）以及所需的具体 NuGet 包。
- [入门](https://ai-game.dev/zh-hans/docs/wiki/godot/getting-started)：首次连接、最初的提示词，以及如何检查一切是否正常。
- [连接 AI 客户端](https://ai-game.dev/zh-hans/docs/wiki/godot/connecting-ai-clients)：Cloud 端点与自建服务器的区别、设备登录、项目密钥，以及针对每种代理的 `setup-mcp`。
- [配置](https://ai-game.dev/zh-hans/docs/wiki/godot/configuration)：AI Game Developer 停靠面板、已保存的设置和 `GODOT_MCP_*` 环境变量。
- [工具](https://ai-game.dev/zh-hans/docs/wiki/godot/tools)：内置的工具系列、RQL，以及每个工具的用途。
- [自定义工具](https://ai-game.dev/zh-hans/docs/wiki/godot/custom-tools)：用 C# 编写你自己的 MCP 工具，并从正在运行的游戏暴露工具。
- [扩展](https://ai-game.dev/zh-hans/docs/wiki/godot/extensions)：用于动画、CSG、导航、瓦片地图和热门 Godot 插件的可选包。
- [godot-cli 参考](https://ai-game.dev/zh-hans/docs/wiki/godot/cli)：所有 `godot-cli` 命令及其参数。
- [故障排查](https://ai-game.dev/zh-hans/docs/wiki/godot/troubleshooting)：插件无法加载、代理看不到任何工具、重新加载问题。
- [常见问题](https://ai-game.dev/zh-hans/docs/wiki/godot/faq)：对常见疑问的简短解答。

## 站点上的更多内容

- [安装 Godot MCP](https://ai-game.dev/zh-hans/engines/godot)：Godot 安装页面。
- [Godot 工具目录](https://ai-game.dev/docs/tools/godot) 和 [Godot 扩展](https://ai-game.dev/docs/extensions/godot)。
- [Godot 最佳实践](https://ai-game.dev/docs/best-practices/godot)：如何编写有效的提示词。
- [MCP endpoint](https://ai-game.dev/zh-hans/mcp-endpoint-info) 与[身份验证](https://ai-game.dev/docs/auth)：托管端点以及登录的工作方式。
- [AI Game Dev 应用 wiki](https://ai-game.dev/zh-hans/docs/wiki/app)，以及 [Unity MCP](https://ai-game.dev/zh-hans/docs/wiki/unity) 和 [Unreal MCP](https://ai-game.dev/zh-hans/docs/wiki/unreal) 的 wiki。

- [**安装** 通过 AI Game Dev 应用、godot-cli、Godot 资产库或发布 zip 安装 Godot MCP 插件，并为你的 .csproj 配上准确的 NuGet 包。](https://ai-game.dev/zh-hans/docs/wiki/godot/installation)
- [**快速开始** 将 Godot MCP 连接到云端，接入 Claude Code 等 AI 代理，检查连接，并在 Godot 编辑器中运行你的第一批 AI 提示词。](https://ai-game.dev/zh-hans/docs/wiki/godot/getting-started)
- [**连接 AI 客户端** 通过 ai-game.dev 云端端点或你自己的本地服务器，将 Claude Code、Cursor、Copilot、Codex、Gemini 等 MCP 客户端连接到 Godot MCP。](https://ai-game.dev/zh-hans/docs/wiki/godot/connecting-ai-clients)
- [**配置** 在 AI Game Developer 停靠面板中配置 Godot MCP，选择 AI 智能体可见的工具，并用 GODOT\_MCP\_\* 环境变量覆盖设置。](https://ai-game.dev/zh-hans/docs/wiki/godot/configuration)
- [**工具** AI 智能体在 Godot 编辑器中使用的 Godot MCP 工具：针对节点、场景和资源的 RQL 查询，C# 与 GDScript 脚本，截图以及游戏内工具。](https://ai-game.dev/zh-hans/docs/wiki/godot/tools)
- [**自定义工具** 用 C# 编写你自己的 Godot MCP 工具，在主线程执行 Godot API 调用，并从运行中的 Godot 游戏里暴露工具、提示和资源。](https://ai-game.dev/zh-hans/docs/wiki/godot/custom-tools)
- [**扩展** 安装可选的 Godot MCP 扩展：AnimationPlayer、CSG、GridMap、导航、粒子、TileMapLayer、Beehave、Dialogic、Phantom Camera 和 Terrain3D。](https://ai-game.dev/zh-hans/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-hans/docs/wiki/godot/cli)
- [**故障排查** 解决常见的 Godot MCP 问题：插件无法加载或编译、Extensions 列表为空、工具缺失、重载报错以及 .NET 10 崩溃。](https://ai-game.dev/zh-hans/docs/wiki/godot/troubleshooting)
- [**常见问题** 关于 Godot MCP（Godot 编辑器的 AI 助手）的简短解答：Godot 版本、GDScript 项目、离线使用、费用、安全性以及导出的游戏。](https://ai-game.dev/zh-hans/docs/wiki/godot/faq)

---

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

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