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

工具

AI 智能体在 Godot 编辑器中使用的 Godot MCP 工具：针对节点、场景和资源的 RQL 查询，C# 与 GDScript 脚本，截图以及游戏内工具。

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

Godot MCP 内置 24 个工具，分为 9 个族。大多数编辑器操作都通过三个 RQL 工具完成，因此智能体只需一种查询语言就能处理节点、场景、资源、文件和编辑器状态，而不必使用几十个彼此独立的工具。本页介绍每个工具族以及智能体在何时使用它。带参数和示例提示词的可搜索列表见 Godot tools catalog。

工具族

族工具用途
rqlrql-query, rql-mutate, rql-schema读取并修改正在运行的编辑器：节点、Godot 属性、场景、资源、文件、项目设置、输入映射、autoload、组、信号以及编辑器状态。
scriptscript-read, script-create, script-update, script-delete, script-attach-to-node, script-validate, script-build, script-executeC# 和 GDScript 文件、附加脚本、校验 GDScript、构建 C# 项目以及在编辑器中运行 C#。
screenshotscreenshot-viewport, screenshot-camera, screenshot-isolated编辑器视口、某个摄像机或单独渲染的某个节点的 PNG 图像。
consoleconsole-get-logs, console-clear-logs正在运行的游戏输出的日志。在编辑器中对应 RQL 的 console 源。
reflectionreflection-method-find, reflection-method-call在运行中的游戏里查找并调用 C# 方法。在编辑器中对应 RQL 的 call。
runtime-errorsruntime-errors-get, runtime-errors-clear运行中的游戏内部抛出的错误。默认关闭。
pingping就绪探测。属于系统工具，不会展示给智能体。
skillsgodot-skill-create, godot-skill-generate编写新的工具文件、重新生成技能文件。系统工具。
sessionsession-close保存并退出由 godot-cli 启动的编辑器。系统工具。

系统工具通过服务器的 /api/system-tools/ 路由访问（例如使用 godot-cli run-system-tool ping），不会列给 AI 智能体。console、reflection 和 runtime-errors 这三个族服务于你自己连接上的正在运行的游戏；参见 Custom tools。

RQL：一种用于编辑器的查询语言

RQL（Reflection Query Language）是编辑器工具的数据层。查询从某个源开始，用 | 分隔的各个阶段对其进行过滤和塑形，而在 rql-mutate 中以 set 或 call 结尾。以下是智能体可能发送的一些示例：

nodes | where class == "OmniLight3D" | select name props["light_energy"]
nodes | where name starts-with "Enemy" | set Visible = false
root | call AddChild("Node3D", "Props")
project | call AddInputAction("jump", ["Key:Space"])
files | sort size desc | first 5 | select path size importedSize
editor | call SaveScene()
  • rql-query 是只读的，返回紧凑的行。
  • rql-mutate 会修改内容。每个目标和值都会先经过校验，因此查询失败时不会改动任何东西。dry_run 可预览改动。每次调用都是一个撤销步骤（编辑器中的 Ctrl+Z）。
  • rql-schema 列出所编辑场景中的源、函数和节点类，或某个类型的成员、方法和 Godot 属性。带上扩展名时，它会打印该扩展的指南。

源包括 nodes、root、selection、scenes、files、folders、classes、console、editor、project、settings、inputActions、autoloads、groups、layers 和 tools。Godot 属性既可以作为 C# 成员访问（Position、Visible），也可以通过 props["snake_name"] 中的 Godot 名称访问，其中也包含 GDScript 变量。RQL 还能处理信号、组、TileSet、Theme、ShaderMaterial 参数和 MeshLibrary。

编辑器调用覆盖场景和文件操作：NewScene、OpenScene、SaveScene、SaveAllScenes、ReloadScene、CreateResource、MoveResource、DeleteResource、CreateFolder、DeleteFolder、Reimport、Undo、Redo、PlayScene 和 StopScene。gameLog 源可读取从编辑器中启动的游戏所打印的内容。

场景编辑会像你自己的编辑一样把场景标记为未保存。被编辑的资源文件和 project.godot 会立即保存。

脚本：C# 和 GDScript

  • script-read、script-create、script-update、script-delete 作用于 .cs 和 .gd 文件。
  • script-attach-to-node 将脚本附加到节点上。
  • script-validate 返回 GDScript 文件的解析和编译诊断信息；不提供路径时，它会检查 res:// 下的所有 .gd 文件。
  • script-build 运行 dotnet build（Debug），以便加载新的 C# 脚本。随后 Godot 会重新加载 C# 程序集，插件重新连接，构建结果（警告或错误）会在重新加载后返回。
  • script-execute 使用 Roslyn 在编辑器中编译并运行 C# 代码。直接编写普通语句即可；最后一个表达式就是结果。它会返回该值以及代码打印的内容。代码片段默认在 30 秒后超时（最长 4 分钟），死循环会返回超时错误，而不会让编辑器卡死。

你也可以从终端调用 script-execute：

godot-cli exec 'EditorInterface.Singleton.GetEditedSceneRoot()?.Name' --path ./MyGodotProject

截图

截图工具会返回模型可以查看的 PNG 图像：screenshot-viewport 捕获编辑器视口，screenshot-camera 从相机节点渲染，screenshot-isolated 则从选定角度单独渲染某个节点。在做视觉改动之后要求截一张图，这样智能体就能检查自己的成果。

游戏内工具

console-*、reflection-* 和 runtime-errors-* 在你的游戏内部运行，而不是在编辑器中运行。除非你的代码主动启用并连接，否则游戏不会暴露任何内容；runtime-errors-get 还需要 WithRuntimeErrorCapture()。它会捕获 GDScript 运行时错误、push_error 和 push_warning、着色器错误（Godot 4.5 及更新版本）以及未处理的 C# 异常，这样智能体就能运行游戏并看到究竟哪里出了问题。设置方法见：自定义工具。

选择智能体可见的工具

每个工具在停靠面板（MCP features、Tools、Open）中以及 godot-cli configure 里都有一个 Visible 开关。隐藏某个工具会将它从智能体的工具列表中移除，从而节省上下文，但并不会阻止它被调用。参见配置。

更多工具

  • 扩展 让 RQL 了解 AnimationPlayer、CSG、GridMap、导航、粒子、TileMapLayer 以及 Beehave、Dialogic、Phantom Camera 和 Terrain3D 插件。
  • 自定义工具 介绍了如何用 C# 编写你自己的工具。
  • Godot 最佳实践 提供了能很好地运用这些工具的提示词模式。