godot-mcp

一个 MCP 服务器，让 AI 智能体像开发者一样在 Godot 4.x 项目上工作：读取和编辑场景、编写脚本、构建、测试、运行、查看结果，并调试出错的地方。

有两件事让它区别于猜测文件格式或盲目执行外部命令：

• 它直接询问 Godot 本身。 场景和资源文件会被结构化地解析并重新序列化（在真实项目语料库上经过往返验证，证明字节级一致），但任何依赖引擎自身行为的东西——C# 内省、着色器编译、输入绑定、编辑器状态——都是通过实际以无头模式运行 Godot 或查询正在运行的编辑器来回答的，而不是凭记忆重新实现 Godot 的语义。

• 它会大声失败。 这个项目中每一个可测量的失败模式——缺少显示、未构建的 C# 程序集、已关闭的编辑器、非 .NET 二进制——都是一个有名称、可区分的错误，并附有解决方法，而不是静默的空结果。关于本项目所依据的测量，请参阅 docs/capability-matrix.md；其中几个测量之所以存在，正是因为显而易见的信号（退出码、非 null 返回值）被证明会撒谎。

50 个工具，按照它们运行所需的条件分为四个层级。完整参考请参阅 docs/tools.md，工具拒绝工作时该怎么做请参阅 docs/troubleshooting.md。

要求

• Node.js >= 20

• 一个 Godot 4.7+ 二进制（能力矩阵是针对 4.7 测量的；其他 4.x 版本预计行为类似，但未经验证）

• 对于任何 C# 工具（build_csharp、run_tests、csharp_script_info、validate_node_property，以及通过 validate_script 处理的 C# 脚本路径）：需要 .NET/mono 构建的 Godot——普通的仅 GDScript 发行版无法加载或内省 .cs 脚本，每个 C# 工具都会提前检测到这一点，并以 NOT_MONO_BINARY 拒绝，而不是中途失败。mono 构建的 --version 输出包含 .mono.，并且附带一个同级的 GodotSharp/ 目录。

• 具体到 C# 工具，还需要 PATH 上有一个 dotnet SDK（build_csharp 和 run_tests 会直接调用它；csharp_script_info 和 validate_node_property 需要已经存在 Debug 构建，这来自 build_csharp 或 build_godot_artifacts）。

Related MCP server: godot-mcp-pilot

安装与构建

git clone <this-repo> godot-mcp
cd godot-mcp
npm install
npm run build

这会生成 dist/server.js，即 MCP 客户端运行的入口点。

配置 MCP 客户端

用 node 将你的客户端指向 dist/server.js，并让它能够找到 Godot 二进制。最简单的配置是显式设置 GODOT_PATH：

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/dist/server.js"],
      "env": {
        "GODOT_PATH": "/path/to/Godot_v4.7-stable_mono_linux.x86_64"
      }
    }
  }
}

服务器如何查找 Godot 二进制

按顺序，先找到的优先：

1. 工具调用中显式传入的 binary 参数。

2. GODOT_PATH 环境变量。

3. 项目自身 vendor/ 目录下捆绑的二进制（最多向下搜索 3 层，优先选择文件名包含 mono 的）——适用于自带 Godot 构建的项目。

4. PATH 上的 godot、godot4 或 godot-mono。

服务器如何查找项目

按顺序：

1. 工具调用中显式传入的 project 参数。

2. GODOT_PROJECT 环境变量。

3. 从服务器进程的工作目录向上逐级查找 project.godot。

如果这些都无法解析到包含 project.godot 的目录，需要项目的工具就会以 PROJECT_NOT_FOUND 失败。

GODOT_MCP_DOCS_CACHE

godot_class_doc 和 search_classes 通过直接询问 Godot 二进制来构建类参考索引，这个过程慢到值得缓存。索引默认写入 $TMPDIR/godot-mcp-docs-cache/<godot-version>/；设置 GODOT_MCP_DOCS_CACHE 可以把它放到持久化的位置。缓存以 Godot 版本为键，因此升级二进制会构建新索引，而不是提供过期的旧索引。如果你的 MCP 客户端在目标项目之外的工作目录中运行服务器，请显式设置 GODOT_PROJECT：

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/dist/server.js"],
      "env": {
        "GODOT_PATH": "/path/to/Godot_v4.7-stable_mono_linux.x86_64",
        "GODOT_PROJECT": "/path/to/your/godot-project"
      }
    }
  }
}

在任何新会话中首先调用 godot_status——它会报告解析出的二进制路径、版本、是否为 mono 构建、显示是否可用、项目根目录，以及 C# 程序集是否已构建，这样智能体（或你）可以在尝试任何操作之前了解实际可行的范围。

四个层级

每个工具都由能够回答它的最低层级来提供服务。如果工具以 TIER_UNAVAILABLE 或 DISPLAY_REQUIRED 失败，原因就在于此：

Tier D 不是独立的传输机制——它是叠加在 Tier B 之上的能力约束。只有 capture_screenshot 属于 Tier D：Godot 没有无头渲染路径，因此截图需要真实的显示，无论是虚拟的还是物理的。run_project 配合 windowed: true 也有同样的要求。

Tier A 工具（大多数场景、节点、脚本和项目配置编辑）在完全未安装 Godot 的情况下也能工作——它们是纯粹的文件操作，并针对一组真实的 .tscn/.tres/project.godot 文件进行了字节级一致的重新序列化测试。Tier B 需要 PATH 上有一个 Godot 二进制和/或 dotnet，或按上述方式解析得到。Tier C 需要编辑器插件（下一节）——在它被安装并且启用了该插件的编辑器正在运行之前，所有五个编辑器桥接工具都会以 TIER_UNAVAILABLE 失败；这是预期行为，不是 bug，错误消息会告诉你适用的是两种不同情况中的哪一种（参见 docs/troubleshooting.md）。

每个工具所属的层级请参阅 docs/tools.md。

安装编辑器插件（Tier C）

五个工具——editor_state、get_selected_node、live_scene_tree、open_scene_in_editor 和 execute_editor_script——通过回环 TCP 套接字与正在运行的 Godot 编辑器通信，而不是启动一个进程。这需要在目标项目中安装并启用一个小的 GDScript 编辑器插件。没有安装工具：写入用户的 addons/ 目录并修改他们的 project.godot，正是本项目的路径监狱纪律要避免自动做的事情。这是一次性手动步骤：

1. 将此仓库中的 addon/godot_mcp/ 复制到目标项目的 addons/ 目录中，使其最终位于 <project>/addons/godot_mcp/plugin.cfg。

2. 启用插件——要么在编辑器中（Project Settings > Plugins > godot_mcp > Enable），要么直接将其添加到 project.godot：

[editor_plugins]

enabled=PackedStringArray("res://addons/godot_mcp/plugin.cfg")

3. 为该项目启动（或重启）Godot 编辑器——无头模式即可（--headless --editor --path <project>），不需要显示。插件在启动时会将握手文件写入 <project>/.godot/mcp_bridge.json；五个工具读取该文件以找到桥接的端口和每会话令牌。

请注意，无头编辑器中的编辑器选中状态始终为空——这是预期行为（get_selected_node 会将"未选中任何内容"报告为正常结果，而不是错误）。

安全性与范围

• 路径监狱。 每个写入路径——场景、脚本、资源、截图输出——都会被解析并要求位于项目根目录之内。任何直接或通过符号链接逃逸出项目根目录的路径，都会在触碰任何内容之前以 PATH_OUTSIDE_PROJECT 被拒绝。

• dry_run。 每个会修改数据的工具都接受 dry_run，并返回统一 diff 而不是写入。在提交更改之前用它来预览变更。

• 没有备份存储。 版本控制就是撤销系统。这是一个刻意的简化——服务器本身没有快照或备份机制。如果你的项目不在版本控制之下，请在每次修改调用之前使用 dry_run，或者开始使用版本控制。

• execute_editor_script 不是沙箱。 它在你实际运行的编辑器进程内执行任意 GDScript，拥有与编辑器本身相同的权限——它可以读取和修改实时的编辑器状态、打开的场景，以及从 GDScript 可以访问的任何其他内容。对待它就像对待把 shell 交给一个智能体一样：适合在你自己的项目上工作的可信智能体，不适合不可信的输入。

测试

npm test

对 tsconfig.json 和 tsconfig.test.json 都运行 tsc --noEmit，然后运行完整的 Vitest 测试套件。几乎每个测试都是解析器级别的：它将预设的 Godot/MSBuild 输出喂给解析器，并对结构化结果进行断言，因此测试套件在未安装 Godot 且没有 .NET 工具链的情况下也能运行，并且保持快速和可移植（CI、容器、两者都未安装的笔记本电脑）。

GODOT_TEST_BINARY

有两个测试块不同：tests/integration/tier-b.test.ts 驱动真实的 Godot 二进制——在磁盘上构建临时项目，并针对它调用 validate_script、check_shaders、run_project 和 godot_class_doc——因为解析器可以永远针对预设文本进行测试，却永远无法证明工具自身的进程启动、参数构建和流读取代码在真实引擎上确实能工作。tests/integration/tier-c.test.ts 对编辑器桥接工具做同样的事情，但有一个实质不同的要求：它必须将真实的 Godot 编辑器作为长期运行的、分离的进程启动（编辑器不会自行退出），并在之后可靠地回收它，包括在测试失败时也是如此。

• 未设置（默认）：两个测试块都报告为 SKIPPED。npm test 中的其他内容不受影响。

• 设置为 Godot 4.7+ 二进制的路径：两个测试块都会针对它实际端到端执行。

GODOT_TEST_BINARY=/path/to/Godot_v4.7-stable_linux.x86_64 npm test

此测试块不需要 mono/.NET 构建。如果你同时也在开发面向 C# 的工具（build_csharp、run_tests），你还需要 PATH 上有一个 dotnet；目前没有相应的门控变量，因为 GODOT_TEST_BINARY 测试块中的测试都不需要它。

文档

• docs/tools.md — 每个工具，按领域分组，包含层级和关键输入。

• docs/troubleshooting.md — 实测的失败模式及其修复方法。

• docs/capability-matrix.md — 本项目行为所依据的实证测量数据。