Godot MCP Enhanced

免费 · 开源 · 安全 —— Godot MCP 赛道里少见提供 「系统化安全防护 + 三层架构 + 运行时控制」的开源方案。

给 AI(Claude Code、Cursor、CodeBuddy 等 MCP 客户端)一个能真正读、写、跑、验证 Godot 项目的 工具层:46 个 MCP 工具(merged,共 272 个 action;完整清单见 capability-matrix)覆盖场景/脚本/UI/动画/物理/粒子/导航/音频/测试/导出/3D 参数化资产(asset:11 shape + 路径阵列 + batch 原子 undo),三层架构 (headless + editor + game bridge)+ 路径白名单 / 注入防御 / sandbox 安全体系。 赛道竞品普遍押注「生成」(authoring),本项目押注「验证」(verification)——QA 编排、回归 diff、操作审计与确定性 playtest 共同构成 AI 游戏开发的持续验证管线(CI for AI-assisted game development)。

English · 工具描述为简体中文,服务中文 Godot 开发者社区;欢迎 i18n PR。

小白上手:不用打开 Godot 编辑器也能做游戏

不懂引擎、不想学编辑器?装好 Godot 后,把需求用一句话告诉 AI(「做一个 2048」「给我的角色加二段跳」),读、写、跑、验证全部由 AI 通过本工具完成,全程可以不打开 Godot 编辑器:

1. 说需求 — AI create_project 建项目、quick_scene / write_script 写场景与脚本;
2. 看效果 — run_and_verify 真跑一遍并做结构化错误分析,screenshot(action capture)截图给你看现在的样子;
3. 迭代 — AI edit_script 改完自动过 validate_scripts 逐脚本编译验证;你只管提意见;
4. 验收 — qa 用结构化测试套件起真游戏跑断言(playtest.seed 锁随机,同输入可复现);verify_delivery 交付门禁检查场景树完整性 + 脚本健康 + 性能;
5. 出错不慌 — editor 层操作全进 Godot 原生 undo 栈,AI 改错一步,打开编辑器一步 Ctrl+Z 即回。

连 Godot 都没装? 一条命令自动安装(官方 GitHub releases,SHA512 同源校验,零预装):

npx godot-mcp-enhanced install        # 默认 latest stable;可加版本 tag 如 4.7.2-stable

装到 ~/.godot-mcp/godot/<version>/ 并自动登记进搜索链与路径白名单;setup 在检测不到 Godot 时也会交互式引导安装。

不想要了? 卸载与安装对称(可移植性:易替换性):

npx godot-mcp-enhanced uninstall --dry-run   # 预览将清理的内容(零写入)
npx godot-mcp-enhanced uninstall --yes       # 移除 15 客户端 godot 注册 + 当前项目 addon/project.godot 引用/bridge 残留
npx godot-mcp-enhanced uninstall --yes --purge  # 连 ~/.godot-mcp/ 共享状态一并删(含下载的 Godot 二进制)

用户自管的 mcp_bridge.gd(内容与包内不一致)保留不删;删除共享状态前扫描实例注册表,在跑实例会点名警示。

直接生成一个能玩的游戏? 内置可玩模板(四件套:可玩 demo + GDD + qa 确定性套件 + CSV 调参表):

npx godot-mcp-enhanced init my-game --template=2048    # 或 snake(贪吃蛇)/ breakout(打砖块)
cd my-game
npx godot-mcp-enhanced qa run qa/2048.qa.md --project .   # 真跑游戏跑确定性断言

零外部资产(色块占位美术),零编辑器预打开即可运行;改玩法 = 编辑 tuning/*.csv → csv_to_resources 重导 .tres → 重启生效;design/gdd/ 内置 8 段游戏设计文档(过 validate_gdd 校验),AI 拿着它继续迭代。

一条命令把游玩过程录成 demo GIF(分享给朋友/发社区):

npx godot-mcp-enhanced gif . --seconds 8 --fps 4              # 默认方向键;breakout 加 --keys left,right

bridge 定频截图 + 按键时间线注入,零依赖自写 GIF89a 编码器(≤256 色精确直通/中位切分量化);产物默认落项目内 dist/demo.gif,项目外路径需 y/N 确认。

导出成网页,浏览器直接玩(分享链接前先本地试玩):

npx godot-mcp-enhanced web .            # 自动装 export templates(首次 ~1GB)→ 导出 → 起本地服务器

headless --export-release 官方路径导出 + 127.0.0.1 防穿越静态服务器,打印 http://127.0.0.1:<port>/ 即可浏览器游玩;之后可用 web --serve-only <导出目录> 直接重玩。

已在用 Claude Code Game Studios 工作室模板?见 CCGS × 本项目集成指南——它管设计流程,本项目管真实运行验证。

不知道从哪开始? 一条龙向导 skill(game-wizard):四档分诊(没想法/模糊/清晰/已有项目)→ 阶段机(环境→造→改玩法→qa 硬门→导出→分享),每个 gate 以 qa 退出码为准——「不问文档写了吗,问游戏跑通了吗」:

npx godot-mcp-enhanced skills install    # 装入 game-wizard(及另外 6 个技能)后对 AI 说「帮我做一个能玩的游戏」

下一步:接入 AI 客户端 — 上面所有能力都经 MCP 提供给 AI 使用。先到 快速开始 用一分钟完成配置(Claude Code / Cursor / ZCode / CodeBuddy 等 15 个客户端),再回来走这条小白路径。

路线图:一条龙六批(分发声量/install/模板/GIF/Web/向导)已全部落地;后续方向见 ROADMAP。

与同类方案对比

本项目不追求"工具数量第一"。 赛道里,godot-mcp-pro 有 175 个工具但闭源收 $15; 免费的 Coding-Solo 仅 13 个。真正稀缺的不是工具数量,而是「免费 + 开源 + 系统化安全防护」——安全维度在赛道内几乎无人设防。 数据截至 2026-06-27(stars / 工具数 / 价格均可能变化,详见各项目仓库)。

维度	本项目	godot-mcp-pro	GDAI MCP	Coding-Solo/godot-mcp	yanhuifair/Godot-MCP 1
价格	免费	$15 买断 2	$19 买断 3	免费 4	免费 1
开源	✅ MIT	❌ server 预编译闭源 2	❌ 3	✅ 4	✅ 1
工具数	46 (matrix)	175 2	~30 2	13 2	386 1
安全特性	✅ 路径白名单 / 注入防御 / sandbox / 确认令牌 / 输出防伪	—	—	—	部分(TCP token) 1
架构	三层 headless + editor + bridge	单 editor WS 2	stdio 2	headless CLI 2	TS server + 编辑器插件 TCP 1
运行时控制（engine-level）	✅ game bridge：读运行时状态 / 输入模拟 / 录制回放 / frame-verify	❌ 仅文件·编辑器层	❌	❌	✅ 11 个 runtime 工具 1
确定性 playtest（冻结/单帧/随机锁定）	✅ freeze / step_until 条件步进 / playtest.seed RNG 锁定 + fixed_delta / snapshot-restore	—	—	—	✅ freeze→step→screenshot(无 RNG 锁定/条件步进)15
Godot 4.5–4.7 兼容矩阵	✅	—	—	—	—(仅声明 4.x)1
中文工具描述	✅	—	—	❌	❌

"—" 表示该项目公开 README 未披露相应能力,不代表必然缺失;欢迎 PR 修正。

不只是文件级 bridge,而是 engine-level 运行时控制。 赛道里多数方案(含闭源商业 SaaS)只能让 AI 读写项目文件,看不到、控不了一个正在运行的游戏。 本项目的 Game Bridge 通过 TCP 连接运行中的游戏:读运行时节点树与属性、GPU viewport 真实截图、属性采样、信号监听、输入模拟、录制回放,外加 frame-verify 反作弊验证——让 AI 真正闭环「改 → 跑 → 验证」,而非停在改文件。

「确定性」分级:帧步进 ≠ 真确定性。 赛道里 "deterministic" 一词正被挪用(有项目把 freeze / 固定帧数 step 标注为 Deterministic,却无 RNG 锁定——同输入不同随机状态,结果仍不可复现)。确定性测试其实分三层:

级别	能力	含义
L1 帧步进	freeze / 固定帧 step / 截图	能「暂停下来逐帧看」
L2 输入时序	帧定时输入时间线(send_input_sequence)	锁定「玩家第 N 帧做了什么」
L3 真确定性	playtest.seed RNG 锁定 + fixed_delta 物理步长锁定 + step_until 条件步进 + snapshot/restore 状态恢复	同输入 + 同 seed ⇒ 跨 run 可复现

本项目三层齐备。截至 2026-08-20,已知竞品最高仅达 L1(freeze/固定帧 step,无 RNG 锁定)或 L2(帧定时输入,无暂停、无 seed)。「AI 测试 AI 写的游戏」要可复现,至少需要 L3。

从 Coding-Solo/godot-mcp 升级? 见 迁移指南 —— 核心能力零丢失,获得三层架构 / 安全 / 验证门禁 / 跨版本矩阵增强。

安全体系

截至 2026-06-27 调研,Godot MCP 赛道内少见提供系统化安全特性的方案。本项目内置多层防护, 适合对可信边界有要求的开发场景:

• 路径访问控制 — ALLOWED_PROJECT_PATHS 白名单(deny-by-default),防 junction / 符号链接绕过。未设置时仅允许当前工作目录;多项目使用时在 MCP 配置的 env 中显式列出:

{ "env": { "ALLOWED_PROJECT_PATHS": "D:/proj/game-a;D:/proj/game-b" } }

• Godot 二进制白名单 — GODOT_MCP_ALLOWED_GODOT_PATHS（分号分隔,realpath 归一）在 godot --version 签名校验之上加硬隔离,防 AI 可控的 godot_path 工具参数/项目 override/env 指向任意二进制被 spawn(任意代码执行)。空 env = back-compat 放行(本地信任场景,签名校验仍兜底);多用户/不可信环境显式列可信路径
• GDScript 注入防御 — 危险 API 模式扫描 + 字符串拼接绕过检测
• 危险操作确认令牌 — 删节点等操作需显式确认
• 输出标记防伪造 — 每次执行随机标记,防 GDScript 伪造 MCP 输出
• 本地运行 — 无远程暴露,无第三方数据上传(注:启动时 update-checker 会查 npm registry,详见下方「匿名遥测」段)
• Web GUI 监控面板（server 进程内嵌） — 默认启动（GODOT_MCP_WEB_GUI=0 关闭）,仅监听 127.0.0.1（无远程暴露）;per-pid 登记于 ~/.godot-mcp/web-gui/（含共享 token.txt,首实例生成后续复用）,浏览器访问凭 token;泄露止损出口 dashboard --rotate-token 一键轮换（已运行实例需重启收敛新值）;files API 复用 ALLOWED_PROJECT_PATHS 白名单（deny-by-default,路径越界即 forbidden）。设置面板（「设置」tab）:配置 Godot 可执行路径（--version 验证并显示版本,godot-paths.json 候选点选）与项目白名单 ALLOWED_PROJECT_PATHS——保存即热生效并持久化 ~/.godot-mcp/settings.json（重启自动重放,GUI 设置优先于客户端注入 env;清除 = 恢复启动时 env 快照;写端点受 READ_ONLY 403 + 机器级审计约束,GODOT_MCP_UNRESTRICTED 不提供 GUI 开关）。纵深细节见 src/web-gui/server.ts（token 恒定时间比较/Origin 白名单/CSP sha256）

以上是防误操作层,不是不可绕过的安全边界。GDScript 拥有完整系统访问权限, 沙箱可被间接方式绕过(call() 动态分派、多步变量构造 API 名、字符串拼接构造 API 名(如 "cu"+"rl"、str("OS")+".execute()")等)。

• 需真正隔离:容器 / VM + GODOT_MCP_ALLOW_UNSAFE=false
• 关闭扫描:GODOT_MCP_SANDBOX=disabled(仅开发)
• 本工具仅限本地可信环境,不提供远程认证或加密

匿名遥测（默认关闭）

opt-in,默认零外传。仅当显式设 GODOT_MCP_TELEMETRY=true 时启用,且阶段 0 endpoint 默认空 = 不发任何数据出进程。

• 收集什么:tool 名 + success bool + duration_ms + 错误分类(经白名单脱敏,非原始文本)+ 加盐 sha256 项目 hash(不可逆推原路径)
• 绝不收集:源码 / 场景内容 / 文件路径 / 项目名 / editor 日志 / 邮箱 IP 账号
• install UUID 存哪:~/.godot-mcp/telemetry-uuid.txt(POSIX 0o600)
• CI 强制关闭:CI=true 时即使 opt-in 也忽略,防 CI 触发合成事件

⚠️ 诚实披露 update-checker 外传点:本仓库每次 MCP server 启动时,src/core/update-checker.ts 的 fetch(REGISTRY_URL) 会被动 fetch https://registry.npmjs.org/godot-mcp-enhanced/latest(24h 缓存)。此行为与遥测无关但涉及「数据离开本机」。v0.25.7 起支持 GODOT_MCP_UPDATE_CHECK=false(或 0/no/off,大小写不敏感)关闭启动外传;self_update check action 经 force:true 短路此门控,且 risk='read' 不经确认令牌,AI 可自主调用触发外传(IP/UA 泄漏 npmjs.org)。严格零外传需防火墙或 readOnly 模式拒整工具。CLI 下载链(install/web 的 GitHub releases 下载,用户主动触发)是另一独立出网点,详见 docs/telemetry.md。

代理环境变量(实测口径):Node 原生 fetch(undici)默认不读 HTTP_PROXY/HTTPS_PROXY/NO_PROXY 环境变量(Node ≥24 可设 NODE_USE_ENV_PROXY=1 启用)。实测设必拒代理端口后 fetch registry.npmjs.org 仍直连 200。企业代理环境下更新检查实际直连(可能被防火墙静默拦截);NO_PROXY 不是零外传的有效手段。详见 docs/telemetry.md 代理环境变量节。

⚠️ 诚实披露 vision-router 外传点: screenshot analyze action 设 vision_route=true + GODOT_MCP_VISION_KEY 时，截图 base64+prompt 外传到 https://api.groq.com（groq 视觉模型）。双重 opt-in 默认零外传（不传 vision_route 或不设 key → fallback 本地 detail 分层，零外传）。可设 GODOT_MCP_VISION_BASE_URL 指向自建/ollama/国内中转避免外传到 groq。详见 docs/telemetry.md。

Blender 建模（execute_bpy）安全模型

execute_bpy 通过 headless blender --background 跑 AI 写的 bpy 片段。bpy 是全功能 Python， 无语言层沙箱，威胁面 = 宿主 RCE（读/删任意文件、执行任意命令、网络）——高于 execute_gdscript 的 GDScript 沙箱一个量级（GDScript 语言层有约束，逃逸才到宿主）。

诚实边界：

1. glb 导出落点硬约束：export_path 经 resolveWithinRoot，仅约束 godot-mcp 注入的 export 行 filepath，不约束 bpy 代码内部的 open()/os.remove()/os.system()。
2. 本地单用户信任模型 + 响应附 [SECURITY] warning。
3. 不做 bpy 语法沙箱（正则防不住动态构造 = 假绿），列 backlog。

对比 BlenderMCP：不是"我们防住了它们没防住的"，而是"我们显式声明 fail-model + glb 落点硬约束 + 本地信任模型，BlenderMCP 既无约束也无声明"。

核心能力

三层架构 — 静态编辑 / 实时调试 / 运行时验证

不是单一连接,而是按场景分工的三层(自动检测,互不冲突):

层	连接方式	适用场景
Headless CLI	独立 Godot 进程	文件读写、批量创建、一次性验证(默认)
Editor WebSocket	连接运行中的编辑器	实时操作当前场景、Undo、场景树同步
Game Bridge	TCP 连接运行中的游戏	E2E 测试、运行时调试、输入模拟、状态验证

editor 层全部写操作注册进 Godot 原生 undo 栈(10 个生产命令文件、53 处 action 注册,递归含 commands/asset/ 子目录,核查命令 grep -rc "create_action" addons/godot_mcp_server/commands/ | grep -v ":0")——AI 改错任何一步,编辑器里一步 Ctrl+Z 即回;undo 覆盖面为同赛道最宽。

动态 GDScript 执行

execute_gdscript 让 AI 在 headless 模式执行任意 GDScript:代码片段模式(自动包装 extends SceneTree)、结构化输出(_mcp_output)、超时控制、Autoload 上下文(load_autoloads=true)、结构化错误(类型/文件/行号/修复建议)。

AI 开发闭环 — 不只是工具堆砌

read_scene / read_script → 理解结构 → write_script / edit_script
→ run_and_verify(错误分析)→ validate_scripts → verify_delivery(交付门禁)

• verify_delivery — 端到端交付门禁:场景树完整性 + 脚本健康 + 性能 + 自定义断言
• validate_scripts — 逐脚本执行 Godot load() 编译验证(非项目级完整编译,后者用 npm run check:gdscript),捕获 headless 遗漏的 Parse Error
• dev_loop — 执行 → 验证 → 截图一体化,支持 acceptance 验收标准

闭环示例:AI 用 read_scene 理解 → write_script 改 → run_and_verify(capture_tree=true) 跑+分析 → validate_project 查资源 → batch_add_nodes 批建 → import_resources 注册 → 有问题回到改脚本。

批量操作与资源管理

• batch_add_nodes — 一次调用添加多个节点,只在最后做一次 pack+save,避免每个节点启停 headless Godot
• validate_project — 静态扫描缺失资源、无效 preload()/load() 路径、孤立 .import 文件
• import_resources — 扫描目录批量注册资源(图片/音频/字体/3D 模型),自动生成 .import

结构化开发流程（带 checklist）

对标 agentic skills 方法论（如 obra/superpowers），本项目不止堆工具，还提供 AI 可遵循的结构化开发流程（setup_project_rules 生成到 .claude/rules/godot-mcp-workflow-*.md）：

• Bridge E2E 流程 — install → run(wait_for_bridge) → ping → 操作+wait → 截图/frame-verify 留证
• 改→跑→验证闭环 — read → edit → run_and_verify → validate_scripts → verify_delivery
• 安全编辑流 — search_and_replace 优先 / 改后 validate / 防覆盖 / 确认令牌

每个流程带 checklist + 常见偏离提示，让 AI 少踩坑、按纪律走。

工具一览

共 46 个 MCP 工具(merged tool definition,共 272 个 action),以下按 action 逐项展开全部操作;权威清单见 capability-matrix。

怎么按名找到工具:下表「工具」列绝大多数是 action 名(如 read_scene),实际调用时作为对应顶层工具的 action 参数传入——read_scene/quick_scene 走 scene 工具,read_script/write_script 走 script 工具,以此类推(顶层工具名 = 域名词:scene/script/runtime/validation/game 等 46 个)。action 命名存在三种历史语序(read_scene/tilemap_read/裸 read),不确定时让 AI 先查 help 工具(46 工具全覆盖 + 拼写纠错)。

默认 profile 可见性:默认 basic profile 的 tools/list 返回 26/46 个工具(2026-10-01 真实 stdio 冒烟实测,与 setActiveGroups 静态展开一致;此前文档写 29/46 系把 ALWAYS_ALLOWED 恒可调用项误计入可见数——manage_tools/testing/csv_to_resources 恒允许调用但不在默认 tools/list 列表,语义见 src/core/tool-registry.ts 的 isToolAllowed);ui/tilemap/physics/nav/editor/debug/dap/asset/blender/engine/实例管理(godot_list_instances 等)/android/translation/uid 等域默认不可见,用 GODOT_MCP_PROFILE=full 启动或 AI 运行时 manage_tools activate <组> 动态开启(详见环境变量表与 G7 说明)。

每个工具的完整文档(参数逐个说明/示例)在 docs/tools/ 目录(46 篇,随 npm 分发);工作流教程/故障排查/环境变量详解见 使用指南。

关于「工具数」:本项目用 merged tool 架构——每个顶层 MCP 工具(如 scene)聚合多个 action(如 read_scene/add_node/save_scene)。顶层工具数:46(tools/list 返回条目数,与 capability-matrix 一致);action 总数:272(matrix 的 risk 聚合 read 134+write 112+destructive 10+process 16)。对比竞品统一用「顶层工具数」口径。两个数字均由 npm run build-matrix 从代码自动生成,CI 漂移检测守护。

执行工具

工具	说明
launch_editor	启动 Godot 编辑器 GUI
run_project	以调试模式运行项目（自动超时；preview=true 时窗口常驻至用户关闭，用于改后视觉验证；多项目并行多窗口并存，查错/停止其他项目用 stop_project/get_debug_output 的 project_path）
stop_project	停止运行中的项目，返回结构化输出
get_debug_output	获取分类调试输出（错误/警告/打印）
screenshot	截图三件套:capture 截取游戏画面（Windows 默认窗口模式，Linux/macOS 自动降级）/ analyze AI 分析截图内容（元素识别、缺陷检测）/ diff 像素级双图对比
run_tests	运行 GUT 单元测试并解析结果
get_godot_version	获取 Godot 引擎版本

验证工具

工具	说明
run_and_verify	一键 headless 运行并返回结构化错误/警告分析。支持 capture_tree 选项同时获取场景树快照。自动检测版本不一致和脚本语法错误。
analyze_error	重新分析 Godot 输出文本，提供修复建议
validate_scripts	对每个脚本执行 Godot load() 编译验证（逐文件解析,非项目级完整编译——后者用 check:gdscript）,检测 headless 运行可能遗漏的 Parse Error

动态执行工具

工具	说明
execute_gdscript	在 headless 模式下执行任意 GDScript 代码。支持代码片段模式（自动包装）和完整类模式。设置 load_autoloads=true 可在完整 Autoload 上下文中运行（DataRegistry、PlayerData 等）。
query_scene_tree	加载场景并查询运行时节点树，返回解析后的实际属性值。
inspect_node	深度检查节点：所有属性、信号连接、子节点，支持递归深度控制。

项目工具

工具	说明
list_projects	搜索目录中的 Godot 项目
get_project_info	项目元数据 + 文件统计
list_files	列出文件（支持扩展名/子目录过滤）
read_project_config	解析 project.godot 为结构化 JSON
create_project	创建完整 Godot 项目结构
setup_project_rules	一键配置项目规则（hooks + CLAUDE.md），建议首次使用时运行
validate_project	检查缺失资源、无效脚本引用、孤立 .import 文件
import_resources	扫描目录批量生成 .import 文件（图片/音频/字体/3D模型）

场景工具

工具	说明
read_scene	解析 .tscn 为节点树 JSON，含属性类型解析（ExtResource/Color/Vector2/Vector3/NodePath/数组/字典/数字/字符串）
create_scene	创建新场景
add_node	向场景添加节点
batch_add_nodes	一次调用添加多个节点（比重复 add_node 快得多）
save_scene	保存场景更改
load_sprite	加载纹理到精灵节点
edit_node	编辑节点属性（位置/缩放/旋转/自定义属性）
remove_node	从场景移除节点（需确认令牌）
quick_scene	快速创建场景 + 可选脚本（一步到位）
instance_scene	实例化 .tscn 场景到目标父节点
detach_instance	从场景树分离实例节点
diff_scenes	比较两个 .tscn 场景文件差异
merge_scene	.tscn 冲突解决（三方合并，ExtResource/SubResource ID 重映射）

脚本工具

工具	说明
read_script	读取 .gd/.cs 文件（含元数据）
write_script	写入/覆盖 .gd 文件
edit_script	按行范围编辑 .gd 文件。支持 raw/smart 缩进模式、内容验证、变更前后对比。
generate_test	分析 .gd 文件并生成 GUT 测试脚本
create_test_scene	创建 GUT 测试运行器场景
project_replace	全项目批量搜索替换（CRLF 安全）

运行时操作工具（顶层 signal/audio/physics/node_create_3d 等）

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。如需持久化场景修改，请使用 add_node + save_scene。

工具	说明
signal_connect	连接两个节点的信号。仅影响当前执行上下文。
signal_disconnect	断开信号连接。仅影响当前执行上下文。
signal_emit	发射节点信号，参数仅支持基础类型（string/number/bool/null）。仅影响当前执行上下文。
signal_list	列出节点上可用的信号。
physics_raycast	执行 3D 射线检测，返回碰撞点、法线、碰撞体信息。
physics_body_info	获取物理体的碰撞形状、AABB、碰撞层/掩码信息。
node_create_3d	运行时创建 3D 节点（支持 16 种白名单类型）。headless 创建不持久化。
nav_query_path	查询 3D 导航路径，支持指定 NavigationRegion3D 或自动回退。

音频播放控制工具（顶层 audio,运行时）

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。

工具	说明
audio_play	播放音频资源。支持 AudioStreamPlayer、AudioStreamPlayer2D、AudioStreamPlayer3D 三种节点类型。
audio_stop	停止指定音频播放器的播放。
audio_set_param	设置音频参数：音量 dB、音调缩放、总线路由。
audio_query	查询播放状态（播放中/暂停/停止）、当前播放位置、总线信息。
diagnose_physics	诊断物理体碰撞状态（含 ConcavePolygonShape3D 陷阱检测）。
query_spatial	空间区域查询：碰撞体距离排序，支持碰撞掩码过滤。
collision_overlay	创建碰撞形状彩色线框叠加（StaticBody=蓝/CharacterBody=绿/RigidBody=红/Area=黄）。

TileMap 编辑工具（运行时）

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。如需持久化 TileMap 修改，请使用 execute_gdscript 写入 .tscn 或在编辑器中操作。同时支持 TileMap（旧版）和 TileMapLayer（Godot 4.3+ 新版）两种节点类型。

工具	说明
tilemap_read	读取 TileMap/TileMapLayer 的 cell 数据，返回指定区域内的 tile 坐标、source_id、atlas_coords、alternative_tile。
tilemap_set_cell	设置单个 tile 的源图集和坐标。
tilemap_erase_cell	擦除单个 tile（设为空）。
tilemap_fill_rect	批量填充矩形区域内的所有 tile。
tilemap_clear	清空 TileMap/TileMapLayer 的所有 tile。
tilemap_copy	复制指定区域为模板（内部缓存），用于后续粘贴。
tilemap_paste	将已复制的模板粘贴到目标位置。
tilemap_set_transform	设置 tile 的翻转/旋转变换（水平翻转、垂直翻转、Transpose）。

所有运行时工具支持可选 load_autoloads 参数（默认 true），可在完整 Autoload 上下文中执行。

API 文档工具（顶层 docs——Godot 类文档查询）

工具	说明
get_class_info	获取类的方法、属性、信号、常量
search_classes	按名称/描述搜索类
find_method	查找方法详情（含继承链）
get_inheritance	获取完整继承链

材质与着色器工具（顶层 material,运行时）

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。

工具	说明
material_read	读取节点材质属性和 shader uniform 列表
material_write	设置材质参数、创建/附加/保存材质（.tres）
shader_edit	读写着色器代码、加载 .gdshader、应用模板、编译诊断

Game Bridge 工具

需游戏运行中(bridge autoload 已随项目启动)。除下表 5 个基础 action 外,game 工具还有: game_write(写属性/调方法)、playtest.*(确定性测试:seed/锁步长/单步/快照)、monitor_*(属性采样)、watch_*(信号记录)、find_ui_elements/click_button(UI 发现/点击)、network_conditioner(弱网注入)、sync_state(状态快照对比)、install_override(调试脚本注入)、custom_command(项目自定义命令)。完整清单见 docs/tools/game.md。

工具	说明
game_bridge_install	安装 MCP Bridge autoload 到项目（TCP 服务端,NDJSON 协议,仅 127.0.0.1）
game_bridge_uninstall	卸载 MCP Bridge autoload
game_query	查询运行中游戏状态（场景树/节点属性/性能/视口/截图）
game_input	向运行中游戏发送输入事件（键盘/鼠标/文本/拖拽/输入序列）
game_wait	在 timeout 窗口内轮询等待游戏状态条件（节点出现/属性值变化），支持 interval_ms 探测间隔。条件成立立即返回，超时返回 timed_out

工作流工具（顶层 workflow——dev_loop 执行+验证一体）

工具	说明
dev_loop	开发循环：执行 GDScript → 验证 → 捕获输出，支持 save_state 文件即记忆
scene_snapshot	场景树快照，用于前后对比检测变更
batch_validate	批量验证多个 GDScript 文件

动画工具（运行时）

工具	说明
animation	查询、播放、编辑动画。支持 list_players、get_info、get_details、get_keyframes、play、stop、seek、create、delete、update_props、add/remove_track、add/remove/update_keyframe 等子操作

性能分析工具（运行时）

工具	说明
profiler	性能分析：快照（FPS/内存/绘制调用/物理统计）、采样分析、活跃进程检测、信号连接审计

3D 空间工具

工具	说明
spatial_info	获取 Node3D 空间信息：transform、AABB、bounds、区域查找

测试与导出工具

工具	说明
test_assert	断言场景树状态：node_exists、property_equals、signal_connected、node_count
test_stress	压力测试：重复创建/销毁节点检测内存泄漏
export_list_presets	列出项目导出预设
export_get_preset	获取导出预设详情
export_build	执行导出构建

粒子系统工具（顶层 particles,运行时）

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。

工具	说明
particles_create	创建 GPU 粒子节点（GPUParticles2D / GPUParticles3D）
particles_set_emission	设置发射参数：形状（point/sphere/box/ring）、半径、方向、扩散
particles_set_process	设置处理参数：重力、速度、爆炸性、生命周期、阻尼
particles_load_preset	加载预设效果：fire / smoke / rain / snow / sparkle / explosion
particles_set_material	创建或重置 ParticleProcessMaterial

导航工具（运行时）

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。

工具	说明
nav_create_region	创建 NavigationRegion3D 并可选烘焙导航网格
nav_bake_mesh	烘焙导航网格（长时间操作）
nav_create_agent	创建 NavigationAgent3D 并设置寻路参数
nav_set_params	设置导航代理参数（10 个可配置字段：radius、height、max_speed 等）
nav_create_link	创建 NavigationLink3D 连接点（支持双向）

AnimationTree 工具（顶层 animtree,运行时）

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。

工具	说明
animtree_create	创建 AnimationTree 节点（支持 AnimationNodeStateMachine / BlendTree / BlendSpace2D）
animtree_add_state	向状态机添加动画状态（AnimationNodeAnimation）
animtree_add_transition	在状态间添加转换（含交叉淡入淡出时间和条件）
animtree_set_blend	设置混合参数（float 用于 BlendTree，Vector2 用于 BlendSpace）
animtree_play	切换到目标状态（通过 playback.travel）

IK 框架工具（顶层 animation 的 ik_* action + animation_track）

工具	说明
ik_modifier_create	创建 IK 修改器节点（TwoBoneIK3D / FABRIK3D / CCDIK3D / SplineIK3D / JacobianIK3D）
ik_modifier_get	读取 IK 修改器属性
ik_modifier_set	设置 IK 参数（active、influence、bone_name、target、magnet）
ik_list_bones	列出 Skeleton3D 骨骼

验证交付工具

工具	说明
verify_delivery	端到端交付验证：场景树完整性 + 脚本健康 + 性能 + 自定义断言 + GDD 标准合规

游戏设计工具

工具	说明
validate_gdd	验证游戏设计文档是否符合 8 章节标准（概述、玩家幻想、详细规则、公式、边界情况、依赖、调优旋钮、验收标准）
chain_verify	Chain-of-Verification 自我质疑引擎：对审查结论生成 5 个挑战性问题，防止盲点和过度自信

代码模板工具

工具	说明
list_templates	列出可用代码模板（内置 + 用户自定义）
apply_template	应用代码模板到指定脚本（支持变量替换）

UI 布局工具（运行时）

工具	说明
ui_create_control	创建 UI Control 节点
ui_build_layout	CSS Flexbox/Grid 翻译层，从声明式布局描述构建 Godot Container 树
ui_set_layout	设置 Control 节点布局属性（锚点/偏移/最小尺寸）
ui_get_layout	查询 Control 节点布局信息
ui_anchor_preset	应用锚点预设（full_rect/center/top_wide 等 16 种）
ui_set_theme	设置/创建/保存/加载 Theme
ui_container_add	向 Container 添加子 Control 节点
ui_draw_recipe	声明式绘图操作（rect/circle/line/arc/polygon/string）
theme_create	创建空 Theme 或从节点提取 Theme
theme_set_property	设置 Theme 属性（font/color/constant/stylebox）

录制工具

工具	说明
recording_start	开始录制输入事件（键盘/鼠标）
recording_stop	停止录制并返回事件数据
recording_save	保存录制到 JSON 文件
recording_load	加载录制文件
recording_play	回放录制的输入事件

编辑器同步工具

工具	说明
editor_sync_start	启动场景树实时监听（推送 node_added/node_removed 事件）
editor_sync_stop	停止场景树监听

资源管理工具（UID / 翻译）

工具	说明
uid_scan	扫描项目内全部资源文件的 UID 状态（Godot 4.4+ .uid）：缺 .uid 的资源、孤儿 .uid（主文件不存在）
uid_get	查询文件 UID（单个/批量，res:// 路径）
uid_set	写 .uid 文件：指定 uid / 按路径确定性生成（与编辑器一致）/ fix_missing 批量修复缺失
uid_check_refs	扫描文本资源中的 uid:// 引用，检测悬空引用（引用的 UID 不在项目 .uid 集合中）
translation_read	读 CSV（Godot 国际化表格）/ PO（gettext）翻译条目（语言 + 键值对，支持截断）
translation_write	写/创建 Godot 兼容 CSV 翻译表（keys + 每语言一列；CSV→.translation 编译由编辑器导入完成）
translation_register	把 .translation/.po 资源注册进 project.godot 的 internationalization/locale/translations（remove=true 反向移除）

⚠️ 运行时工具(物理 / 动画 / UI / 粒子 / TileMap / 材质等)仅在 headless 执行上下文生效, 不持久化到 .tscn;需持久化用 add_node + save_scene。

调试与诊断工具

Footnotes

1. https://github.com/yanhuifair/Godot-MCP,抓取 2026-08-19(工具数 386 为 grep -c "registry.register(" src/tools/register.ts 实测) ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹

2. https://github.com/youichi-uda/godot-mcp-pro README(含其自带竞品对比表),抓取 2026-06-27 ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸

3. GDAI MCP,数据转引自 godot-mcp-pro 对比表,2026-06-27 ↩ ↩²

4. https://github.com/Coding-Solo/godot-mcp,抓取 2026-06-27 ↩ ↩²

5. 该仓库 README 声称「freeze/step/screenshot No other public Godot MCP does this」——与事实不符:本项目的 playtest.freeze / step_until(结构化条件步进)与 satelliteoflove/godot-mcp(2025-12 起)的 deterministic playtesting 均早于该声明,供读者自行核对。 ↩