本页由英文机器翻译而成。阅读英文原文。

快速开始

将 Godot MCP 连接到云端，接入 Claude Code 等 AI 代理，检查连接，并在 Godot 编辑器中运行你的第一批 AI 提示词。

更新于 2026年11月4日 查看 Markdown 版本

本页将带你从已安装的插件走到能编辑 Godot 场景的 AI 代理。这里假设插件已经在你的项目中；如果没有，请先阅读安装。以下步骤使用默认的 Cloud 模式，编辑器和你的代理都连接到 ai-game.dev，你只需登录一次。

第 1 步：打开项目

用 CLI 打开项目：

godot-cli open ./MyGodotProject

open 会先构建 C# 程序集，然后启动编辑器。首次打开时这次构建非常关键：Godot 会立即加载已启用的插件，如果没有构建好的程序集，它会报告无法加载 GodotMcpPlugin.cs 并禁用该插件。如果你改为从 Godot 项目管理器打开项目，请先构建一次（编辑器中的 Build 按钮或 godot-cli build），并且如果 Godot 关闭了插件，再重新启用它。

插件加载后，编辑器的 Output 面板会输出 [Godot-MCP] plugin loaded，AI Game Developer 停靠面板会出现在右上方的停靠区域。

第 2 步：登录

Cloud 模式需要你的 ai-game.dev 账号。任选以下一种方式：

  • 在停靠面板中，保持模式为 Cloud，然后点击 Authorize。浏览器会打开并显示一个短代码，用你的 ai-game.dev 账号批准即可。
  • 在终端中运行 godot-cli login。它使用相同的 OAuth 设备流程，并把凭据保存到 ~/.ai-game-dev/credentials.json，编辑器会自动读取。

每台机器只需登录一次。同一份凭据可用于 Godot MCP、Unity MCP、Unreal MCP、各引擎 CLI 以及 AI Game Dev 应用。该会话会出现在你账号的已连接设备中，你可以在那里撤销它。详情见身份验证。

第 3 步：连接你的 AI 代理

为你使用的代理写入 MCP 配置。以 Claude Code 为例：

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

这会在项目中写入 .mcp.json，其中的 URL 固定指向本项目，因此即使你同时打开多个编辑器，代理也能连到这个编辑器。你也可以在停靠面板中完成同样的操作：在 AI agent 区域选择你的代理，然后点击 Configure。其他代理（Cursor、VS Code Copilot、Codex、Gemini 等）见连接 AI 客户端。

配置写入后，重启代理或重新加载它的 MCP 服务器。如果配置位于项目文件夹中，请从该文件夹启动代理（Claude Code 会从它启动时所在的文件夹读取 .mcp.json）。

第 4 步：检查连接

停靠面板的 Connection 区域显示三个代表点的一行：Godot、MCP 服务器和 AI 代理。当编辑器已连接且代理会话处于活动状态时，三个点都会亮起，代理那一行会显示客户端名称。你也可以在终端中等待编辑器响应：

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

wait-for-ready 会轮询就绪探针（ping）直到它响应，默认最长等待两分钟。status 会报告该项目是否有编辑器在运行，以及服务器是否响应。

在你的代理中让它列出可用工具，或在 Claude Code 中运行 /mcp。你应该能看到 rql-query、rql-mutate、script-create 和 screenshot-viewport 等工具。

第 5 步：第一批提示词

在代理的对话中试试这些提示词。每一条都对应真实的工具调用，因此你可以看到编辑器中的场景发生变化：

  • “添加一个 Node3D 场景，包含一个 Camera3D 和一个 MeshInstance3D 立方体，然后把它保存为 Main.tscn。”
  • “创建 3 个立方体，围成半径为 2 的圆。”
  • “列出场景中所有 OmniLight3D 及其 energy 值。”
  • “为地板创建一个 StandardMaterial3D，并把它的 albedo 颜色设为灰色。”
  • “创建一个包含 public float Speed 的 Player.cs 脚本，把它挂到 Player 节点上，然后构建项目。”
  • “添加一个名为 jump 的输入动作，绑定到 Space 键。”
  • “截取视口的截图，并告诉我你看到了什么。”

代理所做的场景编辑可以撤销：在编辑器中按 Ctrl+Z 即可回退，和你自己的编辑完全一样。场景改动会把场景标记为未保存，所以请让代理保存，或者你自己保存。更多提示词示例见 Godot 最佳实践。

代理能看到什么、不能看到什么

代理通过插件暴露的工具来工作。它可以借助 RQL 读取场景树、Godot 属性（包括 GDScript 变量）、资源、文件、项目设置、输入映射、autoload、控制台和编辑器状态，也可以查看截图。它无法点击编辑器 UI。完整列表见工具和 Godot 工具目录。

想要完全离线使用？

你可以在自己的机器上运行 MCP 服务器，而不用云端服务。在停靠面板中，将模式切换为 Custom 并点击 Start Server：插件会从 GitHub 下载对应的服务器构建，启动它并建立连接。然后让你的智能体指向这个本地 URL。参见 Connecting AI clients。

后续步骤

  • Configuration：停靠面板、日志级别，以及智能体可以看到哪些工具。
  • Extensions：添加 AnimationPlayer、CSG、导航、tilemap 和插件支持。
  • Troubleshooting：如果上述某一步没有成功。