GodotLens

GodotLens：Godot 对你的 GDScript 项目的独到视角

一个 MCP 服务，可让 AI Agent 询问 Godot 本身有关你的项目的信息——某个符号在哪里使用、某个方法的实际签名是什么、修改能否编译、场景如何连接——还可运行游戏、查看游戏并操控游戏，让 Agent 无需真人游玩，也能验证游戏是否按预期运行。

原因

仅凭文本编辑 GDScript 的 Agent 只能猜测。它无法区分调用和注释，无法知道你的 Godot 版本中 CharacterBody2D 有哪些方法，也无法看到 .tscn 中通过名称连接的信号处理函数，更无法看到运行时发生了什么。

GodotLens 从不自行回答这些问题，而是向引擎提问，并返回引擎的答案。在 Godot 4.7.1 上进行测量时，在一个 take_damage 定义于 player.gd、从 enemy.gd 调用两次、从 player.gd 调用一次，且注释中也提到该名称的项目中：

方法	结果
grep take_damage	5 处匹配，其中包括注释
gdscript_references	恰好 4 处真实调用；不包括注释

这一原则——将每一项判断都交给 Godot——让答案值得信赖，也正因如此，工具名称会告诉你答案来自哪里。gdscript_* 是语言服务器。scene_* 和 project_* 会在项目上运行引擎。debug_* 是编辑器的调试器。runtime_* 则表示 GodotLens 启动并连接到的游戏。

要求

	用途
Godot 4.6+ 编辑器已打开你的项目	gdscript_* 和 debug_*——语言服务器和调试适配器运行于编辑器中
通过 GODOT_BIN、./godot/ 目录或 PATH 提供 Godot 二进制文件	scene_*、project_* 和 runtime_*，它们自行运行引擎，无需编辑器
Python 3.10+，或用于 npx 的 Node.js 16+	运行此服务

最低版本要求为 Godot 4.6，因为语言服务器在 4.5（URI 编码）和 4.6（文档所有权）中发生了重大变化。对于更早的版本，系统会明确提示并拒绝运行，而不是悄然误读。

安装

npx（推荐）。该软件包包含服务，无需运行时依赖。

{
  "mcpServers": {
    "godotlens": {
      "command": "npx",
      "args": ["-y", "godotlens-mcp"]
    }
  }
}

pip

pip install godotlens-mcp

{
  "mcpServers": {
    "godotlens": { "command": "godotlens-mcp" }
  }
}

如何运行

设置	可用功能	操作
编辑器已打开 — 常规开发	所有功能	在 Editor Settings（下方）中启用 Import Resources When Unfocused。
没有编辑器 — CI、脚本	scene_*、project_*、runtime_*	如需使用 gdscript_* 和 debug_*，请启动无头编辑器：godot --path <project> --editor --headless --lsp-port 6005 --dap-port 6006
由 GodotLens 启动的游戏（runtime_run）	runtime_*，可与上述任一模式同时使用	无需操作。每个游戏都是独立进程，会连接到 GodotLens；不会占用编辑器的运行槽位。

Import Resources When Unfocused。 只有当编辑器窗口获得焦点时，编辑器才会检测新增和更改的文件。由 Agent 驱动的编辑器永远不会获得焦点，因此新的 class_name 脚本会一直无法识别——所有使用它的脚本都会报告名称未声明，导致游戏解析失败——而新增资源也不会被导入。启用此设置后，编辑器每半秒重新扫描一次。Godot 4.7 中该设置位于 interface/editor/behavior/import_resources_when_unfocused，4.6 中位于 interface/editor/import_resources_when_unfocused；如果只想为一个项目设置，请在 project.godot 的 [editor_overrides] 下添加 4.6 中的设置名称（4.7 会在加载时迁移该设置）。当同步的文件引用了编辑器尚未注册的类时，gdscript_sync_file 会短暂等待，然后说明是哪一个类，并指向此处。

由 GodotLens 启动的游戏。 runtime_run 会通过 --remote-debug 指向 GodotLens 来启动游戏，因此游戏会像连接编辑器调试器那样连接到 GodotLens。游戏默认以无头模式运行——没有窗口、没有声音，也不会获得焦点。仅在使用 runtime_screenshot 时传入 windowed: true：窗口会在远处的位置打开，并静音，随后完全移出屏幕，因此最多只有一个小角落会短暂显示。 脚本错误会被报告，但不会停止游戏。以这种方式启动的游戏会在停止时、GodotLens 退出时结束；在 Windows 上，即使直接强制结束 GodotLens，游戏也会结束。它的日志与 GodotLens 启动的每次引擎运行一样，都会写入单独的临时文件：Godot 每个项目只保留最新的五份日志，你自己的游玩和测试日志也会保留在其中。

辅助脚本。 runtime_eval 和 runtime_input 需要在游戏中运行代码。GodotLens 会在本次运行期间通过 --script 将自己的 helper.gd 传给游戏；不会向你的项目写入任何内容。Godot 仍会加载项目设置、输入映射和自动加载项，而辅助脚本会打开场景。如果项目设置了自己的主循环类型，游戏会在不使用辅助脚本的情况下运行；使用 helper: false 调用 runtime_run 则会完全按原样运行游戏。

多个 Agent。 同一个 Claude Code 会话中的子 Agent 会共用一个 GodotLens 进程（gdscript_status 和 runtime_status 会报告其 server_pid）。调用会并发运行，因此耗时较长的 runtime_run 或场景检查不会阻塞其他人的查询，并且每个 Agent 都可以使用 runtime_run 运行自己的游戏（GODOT_RUNTIME_MAX_SESSIONS，默认值为 4）。有两点不会协调：debug_run 使用编辑器唯一的运行槽位，因此第二次运行会停止第一次；两个 Agent 写入同一个文件时会互相覆盖——请一次只让一个 Agent 写入。

循环

这些工具围绕一个循环设计。读一遍，本文档其余部分可作为参考。

flowchart LR
    U["<b>Understand</b><br/>gdscript_find<br/>gdscript_references<br/>gdscript_hover"]
    W["<b>Write</b><br/>gdscript_engine_api<br/>gdscript_complete<br/>gdscript_validate"]
    S["<b>Sync</b><br/>gdscript_sync_file"]
    V["<b>Verify</b><br/>gdscript_diagnostics<br/>scene_validate<br/>project_validate"]
    R["<b>Run</b><br/>runtime_run"]
    O["<b>Observe &amp; act</b><br/>runtime_tree · runtime_inspect<br/>runtime_output · runtime_eval<br/>runtime_input · runtime_screenshot"]

    U --> W --> S --> V --> R --> O
    O -- "fix, then runtime_reload" --> W
    O -- "something is wrong" --> U

    classDef step fill:#f5f7fa,stroke:#4a6785,stroke-width:1px,color:#1b2733;
    class U,W,S,V,R,O step;

1. 理解。 gdscript_find 按名称定位符号；gdscript_references 和 gdscript_hover 说明符号的用法和类型。
2. 编写。 gdscript_engine_api 提供真实签名，而非凭记忆回忆出的签名； gdscript_complete 提供场景感知的候选项，gdscript_validate 则会在拟定内容写入磁盘 之前进行检查。
3. 同步。 Godot 的语言服务器不会监视文件系统。编辑 .gd 文件后，请调用 gdscript_sync_file，否则它会继续根据旧文本作答。
4. 验证。 使用 gdscript_diagnostics 检查编译错误，使用 scene_validate 检查编译器 无法在场景中发现的问题，移动文件后使用 project_validate。
5. 运行。 runtime_run 启动游戏并返回首条输出和错误。
6. 观察并操作。 查看实时树和数值、按下输入、计算表达式、截取屏幕截图；修复代码后， 使用 runtime_reload 将其重新加载到正在运行的游戏中。

以下约定适用于全文：

• 所有行和字符参数均从 0 开始索引，与 LSP 一致。编辑器中的第 1 行是 第 0 行。gdscript_find 的设计目的之一，就是让你很少需要手动计算索引。
• 在相关情况下，结果会带有 verified 标志。如果 verified: false 且诊断列表为空， 表示 Godot 没有返回结果——这并不代表一切正常。

工具

理解代码

工具	描述
gdscript_find	按名称定位声明。返回的位置可直接供下方工具使用。
gdscript_definition	符号的定义位置。
gdscript_references	项目范围内的所有引用。在 4.6+ 中，此工具会重新解析每个 .gd 文件，因此开销不小。
gdscript_references_in_file	单个文件中的匹配项。开销小得多。Godot 4.7+。
gdscript_hover	符号的类型信息和文档。
gdscript_symbols	文件的符号树。
gdscript_signature_help	调用位置的参数信息。
gdscript_symbols_batch、gdscript_definitions_batch、gdscript_references_batch	一次调用即可查询多个文件或位置，功能与上述工具相同。

编写代码

工具	描述
gdscript_engine_api	根据当前使用的确切构建版本，提供引擎类或成员的签名和文档，包括从父类继承的成员。使用此工具，而不是凭记忆回忆 Godot API。
gdscript_complete	补全指定位置的内容。唯一的场景感知查询：包括实际的 $NodePath 条目以及所属节点上实际存在的信号。
gdscript_validate	检查拟定内容是否有错误，不会将其写入磁盘。
gdscript_rename	重命名符号。如果 Godot 不允许重命名，则会拒绝；如果名称也出现在它无法更新的场景文件中，则会发出警告。

保持 Godot 同步

工具	描述
gdscript_sync_file	同步一个已修改的文件并返回其诊断信息。对于编辑器尚未注册的新 class_name，会稍作等待。
gdscript_sync_files	一次同步多个文件。
gdscript_release_file	释放文件，使语言服务器重新从磁盘读取。
gdscript_diagnostics	一个或多个文件的错误和警告。
gdscript_status	检查连接。如果行为异常，请从这里开始。

项目和场景

这些工具会运行 Godot 二进制文件，因此场景解析结果与引擎构建时完全一致，包括继承和实例化的场景。它们不会将 .tscn 解析为文本，也不需要编辑器。

工具	描述
project_config	通过 ProjectSettings 获取自动加载单例、输入动作名称、class_name 全局类和主场景，并显示每个文件是否存在。
project_validate	文件移动后不再解析的引用：场景和资源依赖项、自动加载脚本、主场景。UID 仍可解析的引用不会被视为失效。
scene_state	节点树、类型、脚本附加情况、unique_name_in_owner 标志、导出值和信号连接。
scene_validate	检查 Godot 在场景中悄然处理错误的情况。错误：悬空连接、缺失信号、处理函数参数数量错误、未知节点类型、不适用于节点的脚本、缺失父节点、重复名称。警告：未知属性、值类型错误、指向场景中不存在节点的 NodePath。

编辑器中的调试器

Godot 可通过编辑器提供 Debug Adapter Protocol 服务，无需添加插件。这些工具使用编辑器自身的运行槽位——一次只能运行一个游戏——并可用于设置断点。

工具	描述
debug_run	从编辑器运行项目，并返回项目输出的内容和所有结构化错误。args: ["--headless"] 可在无窗口模式下运行。
debug_output	游戏输出——print、stdout、stderr——以及带有文件、行号和堆栈信息的结构化错误（push_error、push_warning、引擎错误和脚本错误）。每次调用时清空。
debug_set_breakpoints	在文件中设置断点。
debug_stack_trace	执行暂停处的调用堆栈。为空表示未暂停。
debug_inspect	按作用域查看堆栈帧中的变量。
debug_evaluate	在断点处计算表达式。如果 Godot 会恢复游戏而非返回结果，则拒绝执行。
debug_continue、debug_pause、debug_step_over	执行控制。
debug_terminate	停止正在运行的游戏。
debug_status	显示适配器连接状态，以及游戏是否正在运行或已暂停。

GodotLens 启动的游戏

runtime_run 会将游戏作为独立进程启动，并直接连接回 GodotLens，因此多个 Agent 可各自同时运行一个游戏，无需编辑器。

工具	描述
runtime_run	启动游戏，默认使用无头模式。返回会话 ID，以及游戏的首批输出和错误。
runtime_output	游戏输出的内容及其引发的所有结构化错误，并附带文件、行号和堆栈信息。
runtime_tree	实时场景树，包括运行时创建的节点。
runtime_inspect	查看节点的当前属性值，包括脚本变量。
runtime_set	更改属性并读取其值；值会转换为属性的类型。
runtime_eval	在游戏运行时，针对场景、自动加载项、引擎单例和 class_name 全局类计算表达式。
runtime_input	像玩家一样按下输入动作；is_action_just_pressed 可以检测到。
runtime_reload	热重载已更改的脚本并保留状态。如果脚本无法编译，则拒绝重载。
runtime_screenshot	将窗口模式游戏当前绘制的画面作为图像返回。
runtime_monitors	FPS、帧时间、节点和孤儿节点数量、内存、自定义监视器及其历史记录。
runtime_pause、runtime_time_scale、runtime_step	冻结游戏、减慢游戏速度或逐步执行游戏。
runtime_status、runtime_stop	列出并停止 GodotLens 正在运行的游戏。

限制

在信任结果之前，值得了解以下内容。

语言服务器看不到的内容

• 它只读取 .gd 文件。 在 .tscn [connection] 块中连接的信号处理函数对它不可见，因此重命名该处理函数会导致场景仍指向一个已不存在的方法。这就是 scene_validate 存在的原因，也是 gdscript_rename 会发出警告的原因。
• 自动加载和输入动作名称都是裸字符串。 没有任何机制会验证 GameState.add_score(1) 和 Input.is_action_pressed("jump")。编写它们之前，请对照 project_config 检查。
• 新文件只有通过编辑器的文件系统扫描才能被它发现（参见 如何运行）。扫描只会在文件夹修改时间发生变化时发现该文件夹，而 Godot 记录的时间精度只有整秒，因此在扫描同一秒内创建的文件可能会被漏掉。如果一秒后仍无法识别新类，GodotLens 会在该文件夹中创建并删除一个空的隐藏文件（.godotlens-rescan）——编辑器会忽略点开头的名称——这样下一次扫描就会重新读取该文件夹。不会向项目写入其他内容。
• 在 4.6+ 版本中，gdscript_references 开销很大，因为它会重新解析项目中的每个脚本。只需要检查一个文件时，优先使用 gdscript_references_in_file。

运行游戏

• 无头游戏没有画面。 runtime_screenshot 需要设置 windowed: true，runtime_step 也一样：Godot 只有在下一帧实际绘制后才会再次暂停。
• 热重载只适用于脚本。 已编辑的 .tscn 文件以及新增或已更改的资源都需要重启。编译失败的脚本会在运行中的游戏里被禁用，因此 runtime_reload 会拒绝重载存在错误的脚本——这需要编辑器的语言服务器来检查；没有编辑器时，它会不经检查直接重载，并说明这一点。
• runtime_eval 使用的是 Godot 的 Expression，并非完整的 GDScript：支持调用、运算符和成员访问，不支持语句或赋值。调用会实际执行。
• 断点只在你的编辑器中（debug_*）。debug_evaluate 仅在游戏暂停且当前帧有脚本实例时有效；如果位于静态函数中或因解析错误而中断，它会拒绝执行，因为 Godot 会恢复游戏，而不是返回结果。
• Godot 会限制游戏报告的内容（项目设置 network/limits/debugger/*）：大量打印内容会被引擎截断。
• 在 Linux 和 macOS 上，GodotLens 正常退出时会停止游戏，但被强制终止时游戏仍会继续运行。在 Windows 上，无论哪种情况都会停止游戏（使用作业对象）。

场景和项目检查

• scene_* 和 project_config 会启动自动加载项，就像游戏运行时一样，因此使用自动加载项的脚本可以通过编译。project_validate 和 runtime_monitors 不会启动任何内容。
• 某些场景错误无法通过任何引擎 API 发现。 [sub_resource] 中的未知属性会在加载时被 Godot 丢弃，早于任何代码能够查询它。
• project_validate 会检查场景和资源。 脚本中的 preload() 或 extends 路径无效会导致编译错误，gdscript_diagnostics 会报告此类错误。

一个项目只能开一个编辑器。 同一项目上再开一个编辑器——例如在 GUI 编辑器旁运行无头编辑器——会根据它自身看到的内容重写 .godot/ 的类缓存，并可能删除另一个编辑器注册的类。请将 GodotLens 连接到当前打开的编辑器。

架构

四个通道，一个进程。每组工具恰好对应其中一个通道，因此你可以知道答案来自哪里。

flowchart TD
    Agent["AI Agent<br/>(and its subagents)"]
    GL["<b>GodotLens</b><br/>MCP server · JSON-RPC 2.0<br/>Python 3.10+ · no dependencies"]

    Agent <-- "stdio" --> GL

    GL -- "TCP 6005<br/>language server" --> Editor
    GL -- "TCP 6006<br/>debug adapter" --> Editor
    GL -- "subprocess<br/>--headless --script" --> Binary
    Game -- "TCP, game connects back<br/>remote debugger protocol" --> GL

    Editor["<b>Godot Editor</b><br/>your open editor<br/><i>gdscript_* · debug_*</i>"]
    Binary["<b>Godot binary</b><br/>run on demand<br/><i>scene_* · project_*</i>"]
    Game["<b>Games GodotLens launched</b><br/>one process each<br/><i>runtime_*</i>"]

    classDef svc fill:#eef4fb,stroke:#4a6785,stroke-width:1px,color:#1b2733;
    classDef godot fill:#f3f0fb,stroke:#6b5b95,stroke-width:1px,color:#1b2733;
    class Agent,GL svc;
    class Editor,Binary,Game godot;

MCP、LSP 和 DAP 协议以及 Godot 的二进制值格式都直接基于标准库实现，因此该软件包没有任何运行时依赖项，npm 包也只有少量 .py 和 .gd 文件。

配置

变量	默认值	描述
GODOT_LSP_HOST	127.0.0.1	语言服务器主机
GODOT_LSP_PORT	6005	语言服务器端口。官方 VS Code 扩展使用 6008
GODOT_DAP_HOST	127.0.0.1	调试适配器主机
GODOT_DAP_PORT	6006	调试适配器端口，供 debug_* 使用
GODOT_BIN	auto	Godot 可执行文件，scene_*、project_* 和 runtime_* 必需
GODOT_PROJECT_ROOT	auto	项目根目录；通过向上查找 project.godot 自动检测
GODOT_LSP_TIMEOUT	15	等待单次语言服务器响应的秒数
GODOT_DIAGNOSTICS_TIMEOUT	8	同步后等待诊断结果的秒数
GODOT_VERSION	auto	覆盖功能检测结果
GODOT_FIND_FILE_LIMIT	60	搜索整个项目时 gdscript_find 检查的最大文件数
GODOT_RUNTIME_MAX_SESSIONS	4	runtime_run 同时保持运行的最大游戏数

贡献

pip install -e ".[dev]"
pytest -m "not integration"   # no Godot needed
ruff check .

集成测试会启动真实的无头 Godot；如果没有可用实例，则会正常跳过。只有在明确要求时，或在 Linux 虚拟显示环境下，才会运行打开游戏窗口的那项测试：

GODOT_BIN=/path/to/godot pytest -m integration
GODOTLENS_WINDOWED_TESTS=1 GODOT_BIN=/path/to/godot pytest -m windowed

CI 会在 Linux、Windows 和 macOS 上使用 Python 3.10–3.13 运行测试套件，在这三个平台上使用真实的 Godot 运行集成测试，并安装构建好的 npm tarball 后执行。

许可证

Apache License 2.0——参见 LICENSE 和 NOTICE。