Godot MCP Enhanced
Godot MCP Enhanced is a free, open-source MCP server that gives AI clients a full read → write → run → verify toolchain for Godot projects — 46 merged tools (272 actions) across headless, editor, and live-game bridge layers, with sandboxed security.
Project & file management — list/inspect projects, list files, read/write
project.godot, scaffold new projects from templates (2d-platformer / 3d-fps / visual-novel), generateCLAUDE.md/AGENTS.mdrules and PostToolUse hooks.Scene authoring — read/create/merge/diff
.tscnfiles, add/batch-add/edit/remove nodes, instantiate scenes, one-shotquick_scenewith script, plus batch TileMap/TileSet operations.Scripting & execution — read/write/edit
.gd(line-range or search-and-replace with auto-validate + rollback), execute arbitrary GDScript headless with structured output, generate GUT tests, project-wide replace.Validation & QA gates — headless run with error analysis, per-script compile validation, resource/missing-reference checks,
verify_deliveryrelease gate, GDD structure validation, chain-of-verification, deterministic QA suites with JSON/MD reports and regression diffs.Live-game runtime control (Game Bridge) — inspect scene tree/node properties, write properties and call methods, simulate keyboard/mouse/touch/drag/frame-timed input sequences, freeze/step/
step_until/seed-locked/snapshot-restore deterministic playtests, property monitors, signal watches, UI element discovery + real-event clicks, network condition injection, multi-instance state compare.Screenshots & visual verification — capture game frames, hand images to the client's vision model (or route to an external vision API), pixel-level diff, thumbnail/ASCII token-cost tiers, frame-sequence capture with degradation assertions.
Runtime subsystem tools — audio playback control, materials/shaders, particles + presets, 3D physics raycasts/body info, navigation baking/pathing, AnimationPlayer & AnimationTree editing, IK modifiers, UI/theme building (Flexbox/Grid translation layer), signal connect/emit.
Debug, profiling & analysis — frame- and function-level profiler, DAP breakpoint debugging, live ClassDB introspection, static signal map + change-impact analysis, operation audit log with rollback suggestions, runtime assertions.
Interop & asset pipeline — 3D asset shaping/path arrays/undo, Blender
execute_bpymodeling → glb import, CSV→.trestuning tables, GDExtension C++ scaffolding, Android build/logcat, UID and translation table management, export presets/builds, demo GIF recording, web export.Safety & meta — path whitelisting (deny-by-default), GDScript injection scanning, sandbox and confirmation tokens (via
confirm_and_execute), anti-spoofed output envelopes, localhost-only binding, tool profiles,helpdocs for every tool, session context summary, multi-instance selection, and self-update.
Provides tools for executing Blender Python scripts in headless mode to create and export 3D assets (GLB) for use in Godot.
Provides tools for interacting with Godot Engine projects, including scene editing, script management, running and debugging games, physics queries, and asset management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Godot MCP Enhanced Fix the jump bug in my player script and verify by running the game."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 编辑器:
说需求 — AI
create_project建项目、quick_scene/write_script写场景与脚本;看效果 —
run_and_verify真跑一遍并做结构化错误分析,screenshot(actioncapture)截图给你看现在的样子;迭代 — AI
edit_script改完自动过validate_scripts逐脚本编译验证;你只管提意见;验收 —
qa用结构化测试套件起真游戏跑断言(playtest.seed锁随机,同输入可复现);verify_delivery交付门禁检查场景树完整性 + 脚本健康 + 性能;出错不慌 — 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,rightbridge 定频截图 + 按键时间线注入,零依赖自写 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。
Related MCP server: Gear
与同类方案对比
本项目不追求"工具数量第一"。 赛道里,godot-mcp-pro 有 175 个工具但闭源收 $15; 免费的 Coding-Solo 仅 13 个。真正稀缺的不是工具数量,而是「免费 + 开源 + 系统化安全防护」——安全维度在赛道内几乎无人设防。 数据截至 2026-06-27(stars / 工具数 / 价格均可能变化,详见各项目仓库)。
维度 | 本项目 | godot-mcp-pro | GDAI MCP | Coding-Solo/godot-mcp | yanhuifair/Godot-MCP p4 |
价格 | 免费 | $15 买断 p1 | $19 买断 p2 | 免费 p3 | 免费 p4 |
开源 | ✅ MIT | ❌ server 预编译闭源 p1 | ❌ p2 | ✅ p3 | ✅ p4 |
工具数 | 46 (matrix) | 175 p1 | ~30 p1 | 13 p1 | 386 p4 |
安全特性 | ✅ 路径白名单 / 注入防御 / sandbox / 确认令牌 / 输出防伪 | — | — | — | 部分(TCP token) p4 |
架构 | 三层 headless + editor + bridge | 单 editor WS p1 | stdio p1 | headless CLI p1 | TS server + 编辑器插件 TCP p4 |
运行时控制(engine-level) | ✅ game bridge:读运行时状态 / 输入模拟 / 录制回放 / frame-verify | ❌ 仅文件·编辑器层 | ❌ | ❌ | ✅ 11 个 runtime 工具 p4 |
确定性 playtest(冻结/单帧/随机锁定) | ✅ freeze / step_until 条件步进 / | — | — | — | |
Godot 4.5–4.7 兼容矩阵 | ✅ | — | — | — | —(仅声明 4.x)p4 |
中文工具描述 | ✅ | — | — | ❌ | ❌ |
"—" 表示该项目公开 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.seedRNG 锁定 +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 放行(本地信任场景,签名校验仍兜底);例外(2026-10-13 安全收紧,审查 M-2;2026-10-22 扩至项目 override):AI 可控的godot_path工具参数与项目级 override(.godot/mcp-godot.json/project.godot [godot_mcp]/.godot-version)在白名单未配置时一律拒绝——防"项目内写伪造--version签名的二进制再经参数或项目 override 指向它"的执行链(GODOT_PATH env、godot-paths.json 与自动发现链不受影响;项目 override 被拒时回落 GODOT_PATH env/自动发现,迁移方式=把该 Godot 路径加入白名单);多用户/不可信环境显式列可信路径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与知识库 vault 根目录GODOT_MCP_VAULT_PATH——保存即热生效并持久化~/.godot-mcp/settings.json(重启自动重放,GUI 设置优先于客户端注入 env;清除 = 恢复启动时 env 快照;写端点受 READ_ONLY 403 + 机器级审计约束,GODOT_MCP_UNRESTRICTED不提供 GUI 开关)。资源重导入(项目行「⟳」按钮,2026-10-08):对项目跑godot --headless --import引擎级扫描+重导入变更资源(纹理/音频/字体等导入型缓存),项目运行中时按钮禁用(API 层 409 兜底),完成/失败经 SSE 推送;面板「▶ 运行」前另有 mtime 快检按需自动导入(GODOT_MCP_AUTO_IMPORT=false可关,快检只扫 assets/scenes/scripts 顶层、其他目录变更用「⟳」兜底)。知识库联动(「知识库」tab,2026-10-08,只读):配置 Obsidian vault 根目录后,总览各项目知识库目录的活跃看板进度(任务看板.md/项目待办.mdfrontmatter 计数优先、复选框计数兜底)与最近开发日志,面板内浏览日志正文与看板分节摘要,并提供obsidian://一键跳转;断流检测——解析 vault 根CLAUDE.md「项目目录映射」表关联本地仓库,git 最近 commit 距今 90 天观察窗内晚于最近开发日志超 3 天(或有提交无日志)显示 🔴 停滞警示,定位"代码在动而知识库停滞"的项目。纵深细节见src/web-gui/server.ts(token 恒定时间比较/Origin 白名单/CSP sha256)与src/web-gui/kb-api.ts(只读契约/防穿越)
以上是防误操作层,不是不可绕过的安全边界。GDScript 拥有完整系统访问权限,
沙箱可被间接方式绕过(call() 动态分派、多步变量构造 API 名、字符串拼接构造 API 名(如 "cu"+"rl"、str("OS")+".execute()")等)。
需真正隔离:容器 / VM +
GODOT_MCP_ALLOW_UNSAFE=false关闭扫描:
GODOT_MCP_SANDBOX=disabled(仅开发)本工具仅限本地可信环境,不提供远程认证或加密
Web GUI 面板 token 的防护等级 = 防"他用户/远程",不防同用户进程——
~/.godot-mcp/web-gui/token.txt同 UID 进程可读,凭 token 可经设置面板热改项目白名单等安全边界(审查 M-3 披露,2026-10-13)。同用户进程不可信的场景用GODOT_MCP_WEB_GUI=0关闭面板(默认开启)
匿名遥测(默认关闭)
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)会被动 fetchhttps://registry.npmjs.org/godot-mcp-enhanced/latest(24h 缓存)。此行为与遥测无关但涉及「数据离开本机」。v0.25.7 起支持GODOT_MCP_UPDATE_CHECK=false(或0/no/off,大小写不敏感)关闭启动外传;self_updatecheck 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 外传点:
screenshotanalyze 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 语言层有约束,逃逸才到宿主)。
诚实边界:
glb 导出落点硬约束:
export_path经resolveWithinRoot,仅约束 godot-mcp 注入的 export 行 filepath,不约束 bpy 代码内部的open()/os.remove()/os.system()。本地单用户信任模型 + 响应附
[SECURITY]warning。不做 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— 逐脚本执行 Godotload()编译验证(非项目级完整编译,后者用npm run check:gdscript),捕获 headless 遗漏的 Parse Errordev_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 Godotvalidate_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 可见性:默认
basicprofile 的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 131+write 115+destructive 10+process 16)。对比竞品统一用「顶层工具数」口径。两个数字均由npm run build-matrix从代码自动生成,CI 漂移检测守护。
执行工具
工具 | 说明 |
| 启动 Godot 编辑器 GUI |
| 以调试模式运行项目(自动超时; |
| 停止运行中的项目,返回结构化输出 |
| 获取分类调试输出(错误/警告/打印) |
| 截图三件套: |
| 运行 GUT 单元测试并解析结果 |
| 获取 Godot 引擎版本 |
验证工具
工具 | 说明 |
| 一键 headless 运行并返回结构化错误/警告分析。支持 |
| 重新分析 Godot 输出文本,提供修复建议 |
| 对每个脚本执行 Godot |
动态执行工具
工具 | 说明 |
| 在 headless 模式下执行任意 GDScript 代码。支持代码片段模式(自动包装)和完整类模式。设置 |
| 加载场景并查询运行时节点树,返回解析后的实际属性值。 |
| 深度检查节点:所有属性、信号连接、子节点,支持递归深度控制。 |
项目工具
工具 | 说明 |
| 搜索目录中的 Godot 项目 |
| 项目元数据 + 文件统计 |
| 列出文件(支持扩展名/子目录过滤) |
| 解析 project.godot 为结构化 JSON |
| 创建完整 Godot 项目结构 |
| 一键配置项目规则(hooks + CLAUDE.md),建议首次使用时运行 |
| 检查缺失资源、无效脚本引用、孤立 .import 文件 |
| 扫描目录批量生成 .import 文件(图片/音频/字体/3D模型) |
场景工具
工具 | 说明 |
| 解析 .tscn 为节点树 JSON,含属性类型解析(ExtResource/Color/Vector2/Vector3/NodePath/数组/字典/数字/字符串) |
| 创建新场景 |
| 向场景添加节点 |
| 一次调用添加多个节点(比重复 |
| 保存场景更改 |
| 加载纹理到精灵节点 |
| 编辑节点属性(位置/缩放/旋转/自定义属性) |
| 从场景移除节点(需确认令牌) |
| 快速创建场景 + 可选脚本(一步到位) |
| 实例化 .tscn 场景到目标父节点 |
| 从场景树分离实例节点 |
| 比较两个 .tscn 场景文件差异 |
| .tscn 冲突解决(三方合并,ExtResource/SubResource ID 重映射) |
脚本工具
工具 | 说明 |
| 读取 .gd/.cs 文件(含元数据) |
| 写入/覆盖 .gd 文件 |
| 按行范围编辑 .gd 文件。支持 |
| 分析 .gd 文件并生成 GUT 测试脚本 |
| 创建 GUT 测试运行器场景 |
| 全项目批量搜索替换(CRLF 安全) |
运行时操作工具(顶层 signal/audio/physics/node_create_3d 等)
注意: 运行时操作仅在 headless 执行上下文中生效,不持久化到 .tscn 文件。如需持久化场景修改,请使用
add_node+save_scene。
工具 | 说明 |
| 连接两个节点的信号。仅影响当前执行上下文。 |
| 断开信号连接。仅影响当前执行上下文。 |
| 发射节点信号,参数仅支持基础类型(string/number/bool/null)。仅影响当前执行上下文。 |
| 列出节点上可用的信号。 |
| 执行 3D 射线检测,返回碰撞点、法线、碰撞体信息。 |
| 获取物理体的碰撞形状、AABB、碰撞层/掩码信息。 |
| 运行时创建 3D 节点(支持 16 种白名单类型)。headless 创建不持久化。 |
| 查询 3D 导航路径,支持指定 NavigationRegion3D 或自动回退。 |
音频播放控制工具(顶层 audio,运行时)
注意: 运行时操作仅在 headless 执行上下文中生效,不持久化到 .tscn 文件。
工具 | 说明 |
| 播放音频资源。支持 AudioStreamPlayer、AudioStreamPlayer2D、AudioStreamPlayer3D 三种节点类型。 |
| 停止指定音频播放器的播放。 |
| 设置音频参数:音量 dB、音调缩放、总线路由。 |
| 查询播放状态(播放中/暂停/停止)、当前播放位置、总线信息。 |
| 诊断物理体碰撞状态(含 ConcavePolygonShape3D 陷阱检测)。 |
| 空间区域查询:碰撞体距离排序,支持碰撞掩码过滤。 |
| 创建碰撞形状彩色线框叠加(StaticBody=蓝/CharacterBody=绿/RigidBody=红/Area=黄)。 |
TileMap 编辑工具(运行时)
注意: 运行时操作仅在 headless 执行上下文中生效,不持久化到 .tscn 文件。如需持久化 TileMap 修改,请使用
execute_gdscript写入 .tscn 或在编辑器中操作。同时支持 TileMap(旧版)和 TileMapLayer(Godot 4.3+ 新版)两种节点类型。
工具 | 说明 |
| 读取 TileMap/TileMapLayer 的 cell 数据,返回指定区域内的 tile 坐标、source_id、atlas_coords、alternative_tile。 |
| 设置单个 tile 的源图集和坐标。 |
| 擦除单个 tile(设为空)。 |
| 批量填充矩形区域内的所有 tile。 |
| 清空 TileMap/TileMapLayer 的所有 tile。 |
| 复制指定区域为模板(内部缓存),用于后续粘贴。 |
| 将已复制的模板粘贴到目标位置。 |
| 设置 tile 的翻转/旋转变换(水平翻转、垂直翻转、Transpose)。 |
所有运行时工具支持可选 load_autoloads 参数(默认 true),可在完整 Autoload 上下文中执行。
API 文档工具(顶层 docs——Godot 类文档查询)
工具 | 说明 |
| 获取类的方法、属性、信号、常量 |
| 按名称/描述搜索类 |
| 查找方法详情(含继承链) |
| 获取完整继承链 |
材质与着色器工具(顶层 material,运行时)
注意: 运行时操作仅在 headless 执行上下文中生效,不持久化到 .tscn 文件。
工具 | 说明 |
| 读取节点材质属性和 shader uniform 列表 |
| 设置材质参数、创建/附加/保存材质(.tres) |
| 读写着色器代码、加载 .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。
工具 | 说明 |
| 安装 MCP Bridge autoload 到项目(TCP 服务端,NDJSON 协议,仅 127.0.0.1) |
| 卸载 MCP Bridge autoload |
| 查询运行中游戏状态(场景树/节点属性/性能/视口/截图) |
| 向运行中游戏发送输入事件(键盘/鼠标/文本/拖拽/输入序列) |
| 在 timeout 窗口内轮询等待游戏状态条件(节点出现/属性值变化),支持 |
工作流工具(顶层 workflow——dev_loop 执行+验证一体)
工具 | 说明 |
| 开发循环:执行 GDScript → 验证 → 捕获输出,支持 save_state 文件即记忆 |
| 场景树快照,用于前后对比检测变更 |
| 批量验证多个 GDScript 文件 |
动画工具(运行时)
工具 | 说明 |
| 查询、播放、编辑动画。支持 list_players、get_info、get_details、get_keyframes、play、stop、seek、create、delete、update_props、add/remove_track、add/remove/update_keyframe 等子操作 |
性能分析工具(运行时)
工具 | 说明 |
| 性能分析:快照(FPS/内存/绘制调用/物理统计)、采样分析、活跃进程检测、信号连接审计 |
3D 空间工具
工具 | 说明 |
| 获取 Node3D 空间信息:transform、AABB、bounds、区域查找 |
测试与导出工具
工具 | 说明 |
| 断言场景树状态:node_exists、property_equals、signal_connected、node_count |
| 压力测试:重复创建/销毁节点检测内存泄漏 |
| 列出项目导出预设 |
| 获取导出预设详情 |
| 执行导出构建 |
粒子系统工具(顶层 particles,运行时)
注意: 运行时操作仅在 headless 执行上下文中生效,不持久化到 .tscn 文件。
工具 | 说明 |
| 创建 GPU 粒子节点(GPUParticles2D / GPUParticles3D) |
| 设置发射参数:形状(point/sphere/box/ring)、半径、方向、扩散 |
| 设置处理参数:重力、速度、爆炸性、生命周期、阻尼 |
| 加载预设效果:fire / smoke / rain / snow / sparkle / explosion |
| 创建或重置 ParticleProcessMaterial |
导航工具(运行时)
注意: 运行时操作仅在 headless 执行上下文中生效,不持久化到 .tscn 文件。
工具 | 说明 |
| 创建 NavigationRegion3D 并可选烘焙导航网格 |
| 烘焙导航网格(长时间操作) |
| 创建 NavigationAgent3D 并设置寻路参数 |
| 设置导航代理参数(10 个可配置字段:radius、height、max_speed 等) |
| 创建 NavigationLink3D 连接点(支持双向) |
AnimationTree 工具(顶层 animtree,运行时)
注意: 运行时操作仅在 headless 执行上下文中生效,不持久化到 .tscn 文件。
工具 | 说明 |
| 创建 AnimationTree 节点(支持 AnimationNodeStateMachine / BlendTree / BlendSpace2D) |
| 向状态机添加动画状态(AnimationNodeAnimation) |
| 在状态间添加转换(含交叉淡入淡出时间和条件) |
| 设置混合参数(float 用于 BlendTree,Vector2 用于 BlendSpace) |
| 切换到目标状态(通过 playback.travel) |
IK 框架工具(顶层 animation 的 ik_* action + animation_track)
工具 | 说明 |
| 创建 IK 修改器节点(TwoBoneIK3D / FABRIK3D / CCDIK3D / SplineIK3D / JacobianIK3D) |
| 读取 IK 修改器属性 |
| 设置 IK 参数(active、influence、bone_name、target、magnet) |
| 列出 Skeleton3D 骨骼 |
验证交付工具
工具 | 说明 |
| 端到端交付验证:场景树完整性 + 脚本健康 + 性能 + 自定义断言 + GDD 标准合规 |
游戏设计工具
工具 | 说明 |
| 验证游戏设计文档是否符合 8 章节标准(概述、玩家幻想、详细规则、公式、边界情况、依赖、调优旋钮、验收标准) |
| Chain-of-Verification 自我质疑引擎:对审查结论生成 5 个挑战性问题,防止盲点和过度自信 |
代码模板工具
工具 | 说明 |
| 列出可用代码模板(内置 + 用户自定义) |
| 应用代码模板到指定脚本(支持变量替换) |
UI 布局工具(运行时)
工具 | 说明 |
| 创建 UI Control 节点 |
| CSS Flexbox/Grid 翻译层,从声明式布局描述构建 Godot Container 树 |
| 设置 Control 节点布局属性(锚点/偏移/最小尺寸) |
| 查询 Control 节点布局信息 |
| 应用锚点预设(full_rect/center/top_wide 等 16 种) |
| 设置/创建/保存/加载 Theme |
| 向 Container 添加子 Control 节点 |
| 声明式绘图操作(rect/circle/line/arc/polygon/string) |
| 创建空 Theme 或从节点提取 Theme |
| 设置 Theme 属性(font/color/constant/stylebox) |
录制工具
工具 | 说明 |
| 开始录制输入事件(键盘/鼠标) |
| 停止录制并返回事件数据 |
| 保存录制到 JSON 文件 |
| 加载录制文件 |
| 回放录制的输入事件 |
编辑器同步工具
工具 | 说明 |
| 启动场景树实时监听(推送 node_added/node_removed 事件) |
| 停止场景树监听 |
资源管理工具(UID / 翻译)
工具 | 说明 |
| 扫描项目内全部资源文件的 UID 状态(Godot 4.4+ |
| 查询文件 UID(单个/批量, |
| 写 |
| 扫描文本资源中的 |
| 读 CSV(Godot 国际化表格)/ PO(gettext)翻译条目(语言 + 键值对,支持截断) |
| 写/创建 Godot 兼容 CSV 翻译表( |
| 把 |
⚠️ 运行时工具(物理 / 动画 / UI / 粒子 / TileMap / 材质等)仅在 headless 执行上下文生效, 不持久化到 .tscn;需持久化用
add_node+save_scene。
调试与诊断工具
工具 | 说明 |
| 断点管理(⚠️ editor-only:需 GODOT_MCP_MODE=editor + 插件 + 运行中游戏) |
| TS 直连官方调试协议(DAP TCP 6006):断点/单步/栈帧/REPL,稳定性优先于 debug 工具 |
| 运行中引擎实时 ClassDB 内省 + 节点方法调用(editor-only,补 docs 静态快照缺口) |
| 运行时断言:节点状态/场景结构/屏幕文本/性能基线/截图对比 |
| 静态分析:signal_map 全项目信号连接全景 + impact_check 改动前影响面评估(零 Godot 依赖) |
| 操作审计日志查询(get_log 统计回放 + suggest_rollback 回滚建议) |
| 函数级热点采样(capture_functions)/帧级数据/内存趋势(editor spawn 会话) |
| 多游戏实例发现与切换(多项目并行/E2E 场景) |
| 会话全景:模式/项目/连接/场景快照/工具组/推荐 workflow 一次拿全 |
| 查任意工具完整文档(46 工具全覆盖 + 拼写纠错)——AI 的工具说明书 |
| 未激活工具的代理调用 / 三级 lazy discovery 工具路由查询 |
资产与互操作工具
工具 | 说明 |
| QA 测试套件编排:结构化 spec → 自动装 bridge → 起游戏 → 逐步执行/断言 → 聚合报告 + 回归 diff |
| 测试结果管理(results_get,editor 模式) |
| 3D 资产铺设:create/path(多点串联)/batch/undo/save(运行时,不持久化) |
|
|
| CSV 批量实例化 Resource 并导出 .tres(调参表工作流) |
|
|
| 设备发现/构建安装启动/logcat(Android 开发闭环) |
| 工具组管理:list_groups(含 per-profile 价格)/activate/deactivate/动态发现 |
| 自更新(符号链接校验 + 版本预检) |
| 从本地知识库检索 Godot 开发 SKILL |
MCP 资源(Resources)
AI 客户端可通过 godot:// URI 方案发现和读取项目上下文,无需显式工具调用。
静态资源
URI | 说明 |
| 项目元数据 + 文件统计(JSON) |
| 原始 |
资源模板
URI 模式 | 说明 |
| 读取 |
| 读取 |
| 读取项目中任意文本文件 |
安全限制
路径必须在项目根目录下(禁止
../遍历).godot/、.import/、node_modules/目录被阻止.import、.uid、.godot文件扩展名被阻止
使用示例
Client: ListResources → 发现所有场景和脚本
Client: ReadResource("godot://project/info") → 项目配置 + 统计
Client: ReadResource("godot://scene/scenes/main.tscn") → 节点树摘要
Client: ReadResource("godot://script/scripts/player.gd") → GDScript 源码快速开始
1 分钟配置(推荐)
Claude Code — 全局安装(所有 Godot 项目自动可用)
claude mcp add -s user godot -- npx -y godot-mcp-enhanced为什么用
-s user? Godot MCP 是个人开发工具,你会在多个 Godot 项目中使用它。-s user(user scope)将配置写入~/.claude.json顶层,所有项目自动连接,无需每个项目重复安装。详见 Claude Code MCP 文档。
如果你只想在当前项目使用(不推荐,切项目会丢失):
claude mcp add godot -- npx -y godot-mcp-enhanced # local scope,仅当前项目Cursor / Cline / Windsurf / 其他
在项目的 .cursor/mcp.json 或 MCP 配置中添加:
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "godot-mcp-enhanced"]
}
}
}腾讯 CodeBuddy(国内用户)
CodeBuddy 文档(2026-06-27 实测)支持外部 stdio MCP Server:设置 → MCP 标签 → Add MCP,粘贴与上面相同的 json。也可从其 MCP Market 一键安装(上架后)。
✅ 端到端已验证(2026-07-01):CodeBuddy IDE 内
read_scene读main_3d.tscn成功(返回完整场景结构),stdio MCP 接入跑通。解锁 MCP Market 上架(#10)。
Warp
Warp 终端 原生支持 MCP。Settings → Agents → MCP servers → + Add → CLI Server,粘贴与上面相同的 json(command: npx、args: ["-y", "godot-mcp-enhanced"]);也可写入 ~/.warp/.mcp.json,或开启「Auto-spawn servers from third-party agents」直接复用上面的 Claude Code 配置(零额外配置)。
✅ 协议层实测通过(46 工具全发现、inputSchema 完整、无 integer 参数兼容风险);⚠️ Warp GUI 端到端待补(本机未装 Warp)。完整步骤、兼容性核对表、env /
working_directory说明见 使用指南-Warp。
ZCode(智谱 GLM-5.2 ADE)
ZCode 原生支持 MCP。设置 → MCP 服务器 → 新建(stdio,command: npx、args: ["-y", "godot-mcp-enhanced"]),或写入 <项目根>/.zcode/config.json / .agents/mcp.json。关键:ZCode 不读 CLAUDE.md,只读 workspace 根 AGENTS.md——运行 setup_project_rules(默认双写)生成 AGENTS.md 让 godot 规则生效。
完整步骤、三种配置方式、env / 权限矩阵 / AGENTS.md 注入说明见 使用指南-ZCode。
一键配置
npx godot-mcp-enhanced setup
# 自动检测:Godot 路径 + AI 客户端 + 写入配置
npx godot-mcp-enhanced configure warp
# 定向配置单个客户端(--list 列出全部 15 个,--force 越过未检测闸)
npx godot-mcp-enhanced skills install
# 打包的 7 个 Claude Code skills(game-wizard 向导 + 路由器/安全编辑/验证闭环/bridge E2E/截图留证/Tween 审计)
# 一条命令装入 ~/.claude/skills/(--target <目录> 装项目级,--force 覆盖),
# 指导 AI 更好地调用 godot-mcp 工具——安装摩擦低于手工 MCP 配置,配合 configure 使用验证配置成功
配置完成后重启 AI 客户端会话(MCP 配置只在会话启动时加载),然后二选一验证:
npx godot-mcp-enhanced doctor # 终端诊断:Godot 检测/客户端配置/插件同步逐项 ✓/✗或在 AI 客户端里让 AI 调用 get_godot_version — 返回版本号即链路全通。更多工作流(五个典型闭环/故障排查/环境变量参考)见 使用指南。
首次使用
连接 Godot 项目后,建议立即运行以下工具一键配置项目规则:
setup_project_rules(project_path="你的项目路径")这会自动生成:
.claude/settings.json:PostToolUse hook,每次编辑.gd文件后自动提醒 AI 运行validate_scripts验证语法CLAUDE.md:项目级规则,包含 GDScript 验证规则和发版门禁(verify_delivery检查)
如果已有配置想更新,使用 force=true 覆盖。如只需其中一项,用 hooks=false 或 claude_md=false 跳过。
环境变量
变量 | 说明 | 默认值 |
| Godot 可执行文件路径 | 自动搜索(PATH/注册表/Scoop/Downloads) |
| 项目路径白名单(分号分隔,deny-by-default——未设置时仅允许当前工作目录)。files API/资源读写等均以此校验,路径越界即 forbidden。配置示例: | 未设(限 cwd) |
| 默认项目路径 | 自动检测 cwd(向上搜索 project.godot) |
| 额外 Godot 搜索目录(分号分隔) | 无 |
| Godot 二进制路径白名单(分号分隔,realpath 归一)。空=回落 | 空(回落 config) |
| game bridge 起始监听端口(被占自动递增避让至 +9;多实例并存安全,实际端口写入实例 registry,ping 响应带 pid/project 指纹) |
|
|
|
|
| 启用详细日志 |
|
| 匿名遥测 opt-in(默认关闭,详见 docs/telemetry.md) |
|
| CLI | 未设(latest) |
| 工具 profile(basic/lite/minimal/full/bridge_dev/3d_dev 或逗号组名)。默认 basic(BREAKING from full;lite 9 组省 ~60% context,RCE action 经 action-gate 默认 gated)。回退全量: |
|
|
|
|
|
|
|
| inflight 执行登记目录覆盖(默认 |
|
|
| 开 |
| 分号分隔的 override 脚本路径(启动时注入为 MCPOVERRIDE_* autoload;与 CLI | 未设 |
|
|
|
|
| 开(信封启用) |
⚠️ BREAKING(G7):默认 profile 从
full改basic(对齐 GoPeak compact,省 AI context window)。升级后 tools/list 只暴露 basic(lite 9 组:core/bridge/animation/audio/signal/visual/code/test/profiler)。回退全量 46 工具:GODOT_MCP_PROFILE=full;或 AI 运行时manage_tools activate <groups>动态扩容(无需重启)。RCE action(execute_gdscript 等)始终经 action-gate gated,需GODOT_MCP_PRIVILEGED_GROUPS=code-execution解锁。
注意: 项目路径有 30 秒缓存。切换项目后等待 30 秒或重启 MCP server 使新路径生效。
多版本 Godot 支持
如果你使用 godots 等版本管理器管理多个 Godot 版本,可以为每个项目单独指定 Godot 二进制路径。
优先级:工具参数 godot_path > 项目配置 > GODOT_PATH 环境变量 > PATH > 平台搜索
方式一:项目配置文件(推荐)
在项目目录下创建 .godot/mcp-godot.json:
{
"version": 1,
"godot_path": "/path/to/Godot_v4.6.3-stable_macos.arm64"
}方式二:project.godot 配置段
在 project.godot 末尾添加:
[godot_mcp]
godot_path=/path/to/Godot_v4.6.3-stable_macos.arm64方式三:工具参数
在 MCP 工具调用时传入 godot_path 参数(如 run_project、execute_gdscript 等 10 个核心工具均支持)。
方式四:godots 版本管理器自动检测
在项目根目录创建 .godot-version 文件(内容为版本号,如 4.6.3),MCP server 会自动在 ~/.godots/versions/ 中查找对应版本。
手动配置(高级用户)
git clone https://github.com/wgt19861219/godot-mcp-enhanced.git
cd godot-mcp-enhanced
npm install && npm run build在 MCP 配置中指向 build/index.js,并设置所需环境变量。
常驻守护进程模式(daemon,HTTP 接入)
stdio 模式下 MCP server 的生命周期绑定 AI 客户端会话——客户端退出,server 进程随之消亡,面板、运行中的 Godot 实例上下文一并丢失。daemon 子命令把 server 变成独立后台常驻进程:内嵌 Web GUI 面板 + MCP streamable HTTP 端点(http://127.0.0.1:<port>/mcp,默认端口 9550 起递增),AI 客户端以 type:"http" 直连,客户端开关会话不再影响 server 存活。
godot-mcp-enhanced daemon start [--open] # 拉起后台 daemon;--open 顺手开面板浏览器
godot-mcp-enhanced daemon stop [--force] # 停止(主路走受控关停端点;--force 直接强杀进程树)
godot-mcp-enhanced daemon status [--show-token] # 查看实例清单;--show-token 显示全量 token
godot-mcp-enhanced daemon restart [--open] # 重启(活实例走受控交接,端口不漂移;死实例等价 start)daemon start 成功后打印面板地址、/mcp 端点地址(token 打码)与 token 获取方式;完整 token 用 daemon status --show-token 获取。
与 web / dashboard 的区别(三者都是 CLI 子命令,勿混淆):
命令 | 性质 | 说明 |
| 常驻后台进程管理 | 独立后台进程,面板与 |
| 一次性导出试玩 | 单项目 Web 导出 + 本地服务器供浏览器试玩,不是 MCP 服务 |
| 监控面板入口 | 默认 TUI; |
客户端配置(http 直连)——ZCode(.zcode/config.json 的 mcp.servers,或等价的 .agents/mcp.json):
{
"mcp": {
"servers": {
"godot": {
"type": "http",
"url": "http://127.0.0.1:<port>/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
}Claude Code(mcpServers 键,字段同形):
{
"mcpServers": {
"godot": {
"type": "http",
"url": "http://127.0.0.1:<port>/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}<port> 是 daemon 实际监听端口(daemon start / daemon status 输出),<token> 是共享 token(daemon status --show-token 全量获取)。/mcp 仅认 Authorization: Bearer 头,无 token 返回 401。
配置契约——daemon 由用户终端拉起(非 AI 客户端 spawn),拿不到客户端注入的 GODOT_PATH / ALLOWED_PROJECT_PATHS 环境变量时,GUI 设置面板就是 daemon 的配置界面:在 daemon 自己的面板「设置」页配置 Godot 路径与项目白名单,保存即热生效(持久化 ~/.godot-mcp/settings.json,daemon 启动自动重放),无需重启 daemon。终端 env 中的配置仍按既有优先级参与(GUI 设置优先,清除即恢复启动快照)。
诚实边界:
崩溃不自愈:daemon 异常退出(或所在机器重启)后面板与
/mcp一同消亡,需手动daemon start重拉;没有 watchdog、没有开机自启。单会话独占:同一时刻
/mcp只服务一个 MCP 会话——第二个客户端 Initialize 会收到 409(明确拒绝,不静默排队);需要第二个会话时另起 daemon 或连 stdio 实例。localhost http 客户端行为以真机实测为准:各客户端对本地 http MCP 端点的支持程度(重连、会话保活)可能不同,遇到问题优先核对客户端文档。
工具档位与 stdio 同源:daemon 默认
basic档(与 stdio 生产默认一致),拉起 daemon 的终端设GODOT_MCP_PROFILE可调(如=full,缺席时回落GODOT_MCP_MODE的 minimal/lite/full)——daemon 启动时读取该 env,无 CLI 参数面。
致谢
godot-mcp — 原始项目,本项目基于其二次开发(Copyright (c) 2025 Solomon Elias,MIT,见 LICENSE)
Hastur Operation Plugin — 动态 GDScript 执行和结构化输出的灵感来源
Claude Code Game Studios — 借鉴了以下功能概念(在用 CCGS?见 集成指南):
Hooks + Rules 体系 →
setup_project_rules自动生成.claude/settings.json(PostToolUse hook 自动验证 GDScript)和CLAUDE.md(项目编码标准)Gate-check / verify →
verify_delivery端到端交付验证(场景树完整性 + 脚本健康 + 性能 + 自定义断言 + GDD 合规)Workflow pipeline →
dev_loop执行→验证→截图一体化工作流,支持acceptance验收标准和save_state会话记忆GDScript Lint →
validate_scripts内置的静态 lint 层(L015 行级扫描 + 字符串/注释过滤,独立于 load() 编译检查),对标 CCGS 的validate-commit.shGDD 标准 →
validate_gdd8 章节游戏设计文档结构校验,对标 CCGS 的design/gdd路径规则Chain-of-Verification →
chain_verify自我质疑引擎,防止审查盲点代码模板 →
list_templates/apply_template模板系统,对标 CCGS 的 41 个文档模板
系统要求
Godot Engine 4.x(已测试 4.7;4.6/4.5 向后兼容)
Node.js >= 20(与 package.json engines 一致)
GUT 插件(用于
run_tests工具)
screenshot(action capture)根据平台使用不同的渲染策略:
平台 | 模式 | 说明 |
Windows | 窗口模式(默认) | Headless 模式下 viewport 纹理返回 null,必须使用 GPU 上下文 |
Linux | Headless → 窗口模式降级 | Headless + OpenGL3 取决于 GPU 驱动是否支持 |
macOS | Headless → 窗口模式降级 | 与 Linux 相同 |
内置 screenshot_capture.gd 使用 process_frame 信号模式和 call_deferred() 确保场景加载和帧捕获的可靠性。
测试提示: 仓库的 E2E 测试(
test/e2e-*.test.ts)依赖真实 Godot 二进制。设置GODOT_PATH指向本地 Godot 以运行它们;未设置时这些测试被静默跳过(控制台打印[E2E-SKIP]告警),CI 默认不验证真实 Godot 集成——npm test的"全部通过"仅覆盖 TS/GDScript 逻辑,不含真实 Godot 子进程行为。
许可证
MIT — 含上游 Coding-Solo/godot-mcp 版权(Copyright (c) 2025 Solomon Elias)。
路线图
项目方向与里程碑(M1 定位与声量 / M2 健壮性 P0 / M3 安全 P1 / M4 功能补齐 P2)见 ROADMAP.md。
更新日志
完整变更记录见 CHANGELOG.md。
版本 | 日期 | 要点 |
v0.36.0 | 2026-10-23 | 五条建议试点批 B1-B5 + 编辑器 undo 历史上限(40GB 内存事故根治)+ 两轮全维度审查修复 5 批 59 项 + CI 首跑修复:①feat 五条建议试点批 B1-B5(2026-10-19,第三方审查 |
v0.35.0 | 2026-10-14 | Web GUI 面板大版本(知识库联动+国际化+独立窗口+资源重导入)+ 两轮全维度审查修复落地:①知识库联动 tab——配置 Obsidian vault 根目录后,总览各项目活跃看板进度(frontmatter 计数优先/复选框兜底)与最近开发日志,🔴断流检测(git 最近 commit 与最近日志 90 天观察窗比对,"代码在动而知识库停滞"即警示), |
v0.34.1 | 2026-10-04 | 竞品回流落地批(幂等层+内容指纹+传输卫生门禁,方案 |
v0.34.0 | 2026-10-03 | 守护进程专项(daemon)+ 2026-10-01 审查修复收口:①daemon 常驻守护进程(批 A/B/C)——CLI |
v0.33.9 | 2026-09-22 | 布局审计能力批(TMXYH5 两条 🔴 反馈落地,方案+审查修正):① |
v0.33.8 | 2026-09-18 | 2026-09-17 架构审查批 5(O1 哨兵延迟通道收敛,M-7):五条延迟通道(call_method await/click real_event/playtest.step/step_until/input_sequence)从"handler 临时变量×5 + 五种哨兵字符串 + 消费端五段 elif"归一为单例槽 |
v0.33.7 | 2026-09-18 | 2026-09-17 架构审查批 4(bridge 行为对称)+ 批 2/3 定版随行:①M-5 uninstall 判活护栏——删 secret 前查 machine registry 新鲜心跳,在跑实例的 secret 保留并点名(原行为无条件删光,多实例在跑时 TS 侧重连即断);②M-6/O3 sync_state 快照记录来源 project/port,compare 跨项目比对置 |
v0.33.6 | 2026-09-17 | 2026-09-17 架构审查 H-1/H-2 收口(bridge 参数守卫统一收口):① |
v0.33.5 | 2026-09-17 | 插件反馈批次 C(输入注入):09-10「send_mouse_click 对非 Button 控件 gui_input 不触发」与 09-12「headless 注入整链不派发」双双真机定谳为上游不可复现(带窗口+headless 双形态 e2e:Button pressed/Control gui_input/tap 判定链全通);①注入事件显式 device=0 对齐真实管线(global_position 早已在位,timeline 自动跟随);②send_mouse_click/touch x/y 裸 float() 收口 _num 守卫(I-C 漏网点——null 参数 SCRIPT ERROR 静默变 result:null);③bridge 规则双副本补「输入注入管线要点」(坐标口径/排查清单/复杂交互引导,触发 0.33.5 bump)。 |
v0.33.4 | 2026-09-17 | 插件反馈批次 B(scene 序列化:tscn 损坏/数据丢失类):①headless 白名单补 TextureButton/ColorRect(29→31 种,三方+规则模板双副本同步);②add_node 单发 texture 裸字符串(纹理静默丢失)与属性裸数组(color 静默回退默认值)——文本捷径对 res:///uid:// 字符串与 Array 一律 fallback GD 链(load+数学 coerce 后 pack 自动 ExtResource/Color 构造器,真机验证),与 batch 路径对齐;③单发 parent 含场景根名前缀(query_scene_tree 拷贝形态)剥根名对齐 GD 链;④scene 写操作落盘自检——TS 文本路径落盘前 parse 链可达校验(断链拒写)+ GD 六写 handler 落盘后 CACHE_MODE_IGNORE 回读计数比对(损坏 exit 1 非静默成功)。 |
v0.33.3 | 2026-09-14 | per-project 运行会话分桶: |
v0.33.2 | 2026-09-13 | 预览模式: |
v0.33.1 | 2026-09-13 | 竞品启发加固批(2026-09-01 完成延迟合并):①monitor 输出可解释性(对标 satelliteoflove)——properties 返回过滤后实际监控列表+ |
v0.33.0 | 2026-09-13 | 全仓功能审查修复批(patch→minor 口径归位):4 分域审查代理+主审横扫 46 工具/271 action(报告 |
v0.32.21 | 2026-09-12 | P10 批(多人状态同步):game 工具新增 sync_state(masteryee 移植裁剪)——快照/比对两段式:GD 侧 collect_state 收集 |
v0.32.20 | 2026-09-12 | P9 批(DAP 断点调试):新增第 46 个顶层工具 dap——MCP server 作为 DAP client 直连 Godot editor 自带 DAP server(默认 127.0.0.1:6006,引擎官方调试协议),18 action 全会话流(initialize→launch→set_breakpoint→configuration_done→断点命中后 stack_trace/step_over/continue/pause→disconnect);TS 侧 node:net 直连(无 GD 改动,LuoxuanLove 791 行 GD 移植的架构偏离:frame 编解码缩到 ~40 行);三段状态机+断点簿记全量重发(512×256 上限)+SENSITIVE_KEYS 双层清洗(防调试输出泄漏 secret)+loopback 强制;SSOT 审计器首战抓出 3 个未声明键(防线自证);已知边界:只 GDScript/attach 有限/e2e 用 mock DAP server(真 editor 手动路径文档化)。46 工具/270 action。 |
v0.32.19 | 2026-09-12 | P8 批(热加载状态机/参数 SSOT 双防线):P8-1——mcp_commands 自定义命令热加载(LuoxuanLove 移植):运行中改/增/删 .gd 自动重载无需重启(mtime+300ms debounce),quiesce 语义(调用中不换实例),失败回滚旧版本继续服务(reload_failed+last_error),重名先注册者赢, |
v0.32.18 | 2026-09-11 | P6+P7 批(tokenizer 沙箱/语义观察层):P6——GDScript tokenizer 结构化扫描整文件移植(432 行,成员链合并/字符串归一化/首参三分类)+ scanGdscriptSandbox Phase 3 非字面量 load/preload 拦截(堵正则盲区)+ executeGdscriptRuntime 三通道分层(15 runtime 工具只跳 Phase 3 保留 Phase 1/2 防线;架构判断不移植 Erodenn 三级 tier——execute_gdscript 已 100% 确认令牌,Tier 2 重复建设且降级是安全回退)。P7——语义观察层(gua 移植,经独立审查 BLOCKING 清偿后全覆盖):观察通道 observation_profile 参数(debug 直通/player 投影;env 三态门禁:单值 player=host 强制档防 agent 自降级绕过,多值=请求级可选)+ 可见性级联(agent_exposure=private/visible_to_player=false 沿祖先链整藏子树,不可观察节点报 not found 存在性不泄露)+ 字段策略五模式(agent_field_rules meta:omit/redact/replace/quantize/keep,坏规则 fail-closed 降级 redact,运行中改 meta 即时生效)+ 审查 B-1 清偿四读出口全覆盖(get_tree 整枝剪除/wait exists 与 match 基于投影值/report 搭车与 conditions 同语义/call_method get 投影+结构枚举方法 -22+snapshot·restore -23 保真拒绝)+ near×投影联动(P5 钩子清偿:position 有规则的锚点 -11/候选排除,防距离差分反推)+ find_ui_elements 输出 role/label 语义字段(12 类控件适配表,全档位)。45 工具/252 action。 |
v0.32.17 | 2026-09-11 | P5 发现批(discover 评分/near 空间查询):manage_tools 新增 discover action(关键词在全量 45 工具×action 名×schema 属性描述上五维加权评分——工具名×5>action×4>组名×3>属性描述×2>顶层描述×1,返回匹配/所属组/激活态/激活指引;默认 basic 只 ships 25 工具,未激活组的能力可见性由此补全,token 经济学最后一块);find_nodes 新增 near_node+max_distance 近邻查询(gua 移植简化:锚点 Node2D/3D,同维度节点距离升序含 distance 字段,锚点排除,引擎侧计算)。45 工具/252 action。 |
v0.32.16 | 2026-09-11 | P4 效率批(描述瘦身/失焦降速/inflight 报丧):game 工具描述瘦身三巨点(schema 8198→5800B,总 -3.5KB,解释性文本删/结构形状保,被删细节承接进规则文档;尽调边界结论:scene/workflow 的 schema 膨胀是结构形状不可砍);editor 失焦降速对抗(beckett 轻量版,有 MCP 流量时 clamp 进程级 sleep 至 60fps,空闲 10s 恢复,不碰机器级 EditorSettings);inflight 孤儿记录(工具调用 per-pid 登记,进程被杀后下个 server 启动 stderr 报丧"死亡时仍在执行什么",BuildersGate 取消经济学);SLIM_CONFIG 口径勘误(阈值判断在变换前,slim 对 ui 实际生效);check:budget totalSum warn 90→95KB(瘦身后转绿,回弹即警)。45 工具/251 action。 |
v0.32.15 | 2026-09-11 | P3 能力扩展批(弱网注入/真点击验证/项目本地命令/profile 价格标签):network_conditioner 弱网注入(masteryee MultiplayerPeerExtension 装饰器移植,包装多人 peer 出向注入 latency/loss/jitter,多人联机测试独特能力);click_button real_event 真实输入事件路径(press/release 注入 viewport 走完整引擎管道,修复 emit_signal 不切 button_pressed 状态类 bug,响应带信号计数验证);custom_command 项目本地命令目录(游戏开发者丢 .gd 进 res://mcp_commands/ 即扩展 bridge 命令面,custom. 前缀 default deny,regiellis 模式);manage_tools list_groups 加 per-profile 实测 bytes 价格标签(beckett doctor 模式)。新增 fixture 1 组 + 测试 3 文件 27 用例(单元 14/真引擎探针 5/e2e 8)。45 工具/251 action。 |
v0.32.14 | 2026-09-11 | P2 批:函数级 profiling + report 搭车 + freeze 竞争 + 三加固项:函数级 profiling(Erodenn 整文件移植 1056 行,run_project(profiling) + capture_functions 一次调用,函数级热点+最慢帧 top30,真引擎 e2e 过);report 结构化搭车(step/step_until 响应自带终态读数省观察往返,{path,property} 结构化防 RCE);freeze 竞争上报(unfreeze 报 frozen_for_ms/contested_reasserts);.uid 清理+orphan autoload 前置自愈;CLI 退出码单一注册表+CI 静态扫描;drive-relative 路径形态显式拒(实测抓洞)。新增 3 文件 19 测试。45 工具/249 action。 |
v0.32.13 | 2026-09-11 | P1 安全批(输出侧防注入/自资产保护/心跳保活/声明制白名单):nonce 信封输出侧防注入(读回项目内容包随机 nonce 信封+scrub 防伪造,4 读通道 6 接点,六层防御后第一个管"出"的层);FileGuard 插件自资产写保护(拒写 addons/godot_mcp_server/** 与任意位置同名 mcp_bridge.gd,6 守卫点防自毁攻击);心跳保活(长工具每 20s progress 心跳防客户端 idle 杀的"白花钱取消",BuildersGate 取消经济学);GDA_CALLABLE per-node 声明白名单(call_method 第三授权通道,零执行静态枚举 default deny,BLOCKLIST 三通道硬底线,双副本同步触发 bump)。新增 4 文件 18 测试(含真跑 Godot 行为探针)。45 工具/248 action。 |
v0.32.12 | 2026-09-11 | P0 修复批(42 仓深挖尽调三坑,规则模板 bump):callv 参数预检(强转不可达组合——个数不足/超出、String→int 非数字、Dictionary→Object、typed Array——调用前显式拒绝 code -10,防 callv 静默失败返回 null 被误读为成功;严格转换表来自 aigengame 真引擎验证表);.pc 日志 rotate race 双 key 防护(7 fixture + create_project/init 模板关文件日志, |
v0.32.11 | 2026-08-21 | 反馈四坑收口 + 端口竞态缓解落地 + CI e2e 并行竞态修复:bridge 反馈三坑(find_nodes 消费 root 参数限子树搜索(无效 root 报结构化错)、install_override 插 [autoload] 段末尾(游戏单例之后 _ready 直达,免 await 兜底)、call_method 协程双模式(默认返 |
v0.32.10 | 2026-08-21 | 审查修复批三批合入(2026-08-20 六专项审查 17 条全处置,master plan 批 1/2/4;批 3 CLI 参数双形式已随 v0.32.9 七维度批等价合入,分支废弃):批 1 测试基建(弱断言门禁 860→732 恢复 128 预防,e2e workflow 全 skip 假绿 gate,mock 工厂 satisfies+typecheck:helpers CI 门禁);批 2 GD 对称性( |
v0.32.9 | 2026-08-21 | 架构审查修复批 + 七维度全面审核修复批(报告 |
v0.32.8 | 2026-08-20 | 确定性完全体批(护城河研究 H1+叙事正名):bridge 新增 |
v0.32.7 | 2026-08-20 | 分发优先批(竞品横扫行动,除 P0-1 网页提审全项): |
v0.32.6 | 2026-08-19 | tilemap 可选 scene_path(外部贡献 PR#36,thefireKS):tilemap 八个 action 新增可选 |
v0.32.5 | 2026-08-19 | 债务清理批收尾:screenshot_capture 空白检测采样退化修复(线性步进整除视口退化最左单列→10×10 网格分层采样,800×600 类视口不再误报 BLANK);gdEscape→escapeForGdLiteral 转义类闭类三批(纯字面量上下文含 % 路径/值不再被双写,唯一 % 格式串上下文维持 gdEscape);PR-4 终审 Minor 清账(M-1/M-2/M-5,M-4 executor timeout 30s 决策维持);README 口径三处修复+README.en 同款+check-tool-count 防复发(20→24 处);spec §10.5 两决策输入落答(flow FILL h=39 根因=float32 比例锚点残差+HBoxContainer FILL 子高度整数截断;flow 容差维持 2)。43 工具/241 action。 |
v0.32.4 | 2026-08-18 | 原型翻译层单 spawn 合成(PR-4):ui_import_prototype 内部链 build→persist→reload→measure 由两次 Godot spawn(~6s)合成单 spawn——reload 用 |
v0.32.3 | 2026-08-18 | 原型翻译层像素终验(ui_pixel_verify,PR-3):ui 工具新 action——对已构建场景( |
v0.32.1 | 2026-08-18 | 原型翻译层 verify 层(style_verify + flow_verify,PR-2): |
v0.32.0 | 2026-08-17 | 原型翻译层 StyleBox 通道(StyleBox PR-1,bg 为 BREAKING): |
v0.31.4 | 2026-08-17 | QA 断言四件套 + 应用级异步长跑(QA 深化 PR-1a/PR-1b):qa 套件 +4 控制步骤(watch/monitor start |
v0.31.3 | 2026-08-16 | QA 编排收尾 + 双副本 STRICT 门禁 + 原型小修批:B |
v0.31.2 | 2026-08-16 | final review 修复波:规则 4 透明壳收窄——只对推断布局壳 Panel 设 self_modulate,自带视觉控件(ProgressBar/Button/任何显式 type)豁免,修复 HP 条被误设透明壳而 diff 假绿(集成补 HpBar 落盘断言+负例验证);parent_path 根级参照系限制 schema 声明+非 root 时 build_warnings 提示;坏图可区分性实测证据(好图对 0.1762 vs 下半消失合成坏图 0.4797≈2.7 倍,双副本改基线口径);screenshot threshold 显式 null 落默认 0.12 + action 提示补 diff;ui.md 双副本历史 drift 顺带归零。 |
v0.31.1 | 2026-08-16 | 原型翻译层 + 视觉验收: |
v0.30.0 | 2026-08-15 | AI QA 编排 + 理解层 + 协议债(方向拍板 B/C/D,零 GDScript 改动纯 TS 批次):B |
v0.29.0 | 2026-08-15 | 2026-08-14 六批次审查 findings 全量修复(P0×1 + P1×10 + P2/P3,43 commits,双波终审):P0 editor 重连链死修复(编辑器重启后自动恢复)+ 安全面(write_script 沙箱 4 旁路入口封堵/deny-list 拼写/load_skill 白名单/nonce symlink)+ audit 工具复活(生产 bug,0.28.3 特性此前不可见)+ playtest 六项(永久暂停/owner 互斥/paused 保存等)+ 属性写入 no-op 假成功三路对齐 + bridge 订阅断线恢复 + ⚠️ autoload 键名迁移(Breaking,旧项目重跑 game_bridge_install 自动迁移)+ debug/undo GD 修复 + 测试债(debug e2e 首跑/GD 套件/dispatcher 审计 9 场景)+ 披露对齐。发版门禁全绿(verify_delivery 3/3 + e2e L2 真跑 75 passed)。 |
v0.28.3 | 2026-08-13 | 战略批收尾(14 竞品路线图 G1/G3/G7):G3 操作级审计日志(audit.jsonl appendFile 原子追加,危险操作可追溯/回放)+ G1 deterministic playtest control 层(freeze/unfreeze/step_until 结构化条件,规避 RCE)+ G7 能力 profile(basic=9 组/advanced/full,BREAKING:默认 profile 从 full 改 basic,schema 79KB→~30KB 省 ~60% context)。路线图全完成(G2/G3/G1/G7/G8 ✅,G6 实测已有移除)。 |
v0.28.2 | 2026-08-12 | 安全加固 + 威胁模型 + 可观测性 + 审查修复:G2 trace_id + 结构化错误分类 + PII 护栏(速赢批)+ S-1/S-2 bpy-sandbox 双 opt-in + spawn 清单 + S-3 |
v0.28.1 | 2026-08-11 | 安全加固批次 C + 测试质量:批次 C 安全加固(deny-list/symlink/path/debug.evaluate RCE 多点)+ instance_registry 目录权限 Linux 0o700(P2-4)+ 弱断言精确化与接线守护批次(P1-3~P1-5/P2-1/P2-2)+ MULTI_INSTANCE 接入 godot-matrix(P1-2)+ 全批次第三方审查文档。 |
v0.28.0 | 2026-08-09 | CMP-14 debug Phase 2/3 + 后续批次:debug 工具组从 3 action 扩到 10(完整交互式调试器:栈帧/变量/表达式求值/step 控制/继续/暂停/热重载)+ 新建 EditorDebuggerPlugin 子类(debugger_bridge)+ handle_debug_async 异步路由 + 自动打开脚本(修 Phase 1 限制)+ CMP-16-B advanced-proxy 真动态化 + CMP-16-C drift 映射表扩到全 64 method + CMP-9 confirm gate 守护测试。 |
v0.27.0 | 2026-08-08 | CMP-9 双通道通用方法调用 + CMP-16 live schema(竞品 regiellis/godot-mcp-go 深度对标):CMP-9-A editor |
v0.26.0 | 2026-08-08 | P1+P2 批次修复(18 项审查 finding 闭环):GD-R1 |
v0.25.11 | 2026-08-08 | 实时 ClassDB 内省:新增 |
v0.25.10 | 2026-08-08 | debug 组 Phase 1 断点管理:新增 |
v0.25.9 | 2026-08-08 | 竞品 godot-mcp-go 深度对标产出:CMP-1 editor 项目匹配检查(连接建立后校验 project_path,mismatch 拒绝降级,防跨项目误操作;覆盖首次连接 + rebuild + 自动重连三条路径 + junction realpath fallback)+ CMP-2 game bridge runtime error 捕获( |
v0.25.8 | 2026-08-07 | 5 批审查修复闭环:批次1 GDScript 假成功(save_scene/load_sprite/screenshot 失败补 quit(1) + _cmd_playtest_restore Resource 反向转换 + _cleanup_peer_state 漏清 snapshot)+ 批次2 TS 可靠性(resetBridgeState 清 push 子系统 + STARTUP_CLEANUP.finally + health-monitor degraded 不被心跳过早清除 + playtest owner_pid 多 peer)+ 批次3 安全纵深(FileAccess READ 非 Godot 协议拦 + 网络回连 API 进沙箱 + stripLiterals 扩 user://)+ 批次4 测试缺口(P3-6 socket 竞态并发测试 + C# 回滚测试 + 4 CI 守门脚本)+ 批次5 文档收尾(update-checker 门控语义健壮化 + 文档漂移修正)。4534 测试。 |
v0.25.7 | 2026-08-06 | P3 选做三批(审查 SHIPPED WITH NITS):P3-1/P3-2 版本同步收口(server.json/Dockerfile 纳入 version-sync,根治分发产物漂移)+ P3-7 C# 阶段一收尾(project_replace 白名单/read using/edit 验证回滚)+ P3-6 subscriptions/listen(bridge 事件主动推送,watch/monitor push 模式三层改造)+ P2 第三方审查 B-1/I-2/I-3 修复。4517 测试。 |
v0.25.6 | 2026-08-06 | P2 Wave2:P2-4 确定性 playtest 四原语(seed/fixed_delta/step/snapshot/restore)+ P2-5 SEP-2133 extensions 声明(runtime-bridge 发现性)。 |
v0.25.5 | 2026-08-06 | P2 Wave1:P2-1 overrides 注入 autoload(启动前注入调试脚本)+ P2-6 recipe 验证闭环 + P2-2 validate_scripts autoload 纠偏 + P2-3 nodeType RCE 审计白名单收尾。 |
v0.25.4 | 2026-08-05 | P0(6/6)+ P1(7/7)协议层升级:SDK v1→v2( |
v0.25.3 | 2026-08-01 | 全天审查收尾(SHIPPED):P2-12 二期 async 改造引入的 arena 前缀碰撞 BLOCKING 根治(方案 B |
v0.25.2 | 2026-08-01 | P2-12 McpTestSuite 移植(editor 路线,关闭 P1-5):AI 可写标准化 GDScript 测试套件( |
v0.25.1 | 2026-07-31 | 竞品对比批①-④ 落地(审查 SHIPPED WITH NITS):工具数口径修正(21 处漂移 28/29/33/130+→35/203,含 rule-templates 独立副本同步防下游污染)+ |
v0.25.0 | 2026-07-30 | A-RCE 安全批次(headless instantiate_class 白名单堵 |
v0.24.1 | 2026-07-27 | 文档同步修复: |
v0.24.0 | 2026-07-25 | self-update 机制(Godot AI 追赶 3/3:npm 启动检查 + self_update MCP 工具 addon 检查/更新)+ 5 批审查全闭环(A 安全 RCE class_path/路径穿越/symlink + B 可靠性降级链路/资源写原子化17处 + C 正确性协议契约/undo/参数校验 + D 工具治理 asset/android TOOL_GROUPS + E 测试缺口加固10/10)+ batch F 测试覆盖深度(6 task 假绿修复/纯函数单测/安全动态断言/防回归契约/skip 可见化)+ CI Godot 4.6.3/4.7.1 版本矩阵 + ZCode 深度支持/AGENTS.md + orphan 扫描会话隔离 + editor key 多实例误删修复 + take_screenshot null guard,4030 测试 |
v0.23.0 | 2026-07-13 | 安全 CRITICAL(零确认 RCE 复合链 |
v0.22.0 | 2026-07-08 | asset 工具集新工具(11 shape + 路径阵列 discrete/continuous + batch 原子 undo + save 预制件 + 10 材质预设;方案 A 阻塞 continuous ramp 待上游)+ capability-matrix 33 + LICENSE 致谢 AssetForge/Tripo3D |
v0.21.0 | 2026-07-06 | csv_to_resources 新工具(CSV→Godot 资源批量导入,双轨 TS+GDScript)+ ToolAnnotations hints(actionRisks 派生 readOnly/destructive)+ 多轮独立审查核实修复(RCE/ipc/data-import/综合审查 editor 路由 -32601 回退+guard 接线+heartbeat 暂停语义)+ editor 4.7 兼容(EditorInterface/super() 回归/Safe save)+ capability reviewer 设施 + e2e L2 opt-in |
v0.20.0 | 2026-06-30 | cpp GDExtension 脚手架(scaffold_gdextension 生成 8 文件 C++ 工程骨架)+ 全工具验证靶子(real-project 三层 L1/L2/L3 自动化,28 工具正路径)+ 工具行为修复(default-null 统一/run_project isError/timeout race)+ R3/安全审查修复 |
v0.19.1 | 2026-06-27 | 版本元数据同步(manifest/plugin.cfg/README/使用指南)— 功能无变化,补 v0.19.0 npm 元数据漂移 |
v0.19.0 | 2026-06-27 | R2 审查响应链 — editor 4 模块 undo_manager(nav/particle/animtree/ui Ctrl+Z 撤销) + super() IMP-4 + IMP-11 touch 双侧契约 + 安全同源 4 点(UI/audio/instance) + @748 detach 双 parent fix + 阶段1b 守卫,2894 测试 |
v0.18.2 | 2026-06-18 | 安全加固 — 沙箱绕过组 + 防御深度 + 注入收敛,2670 测试 |
v0.18.1 | 2026-06-14 | 功能验证审查 3 CRITICAL 修复 — parseTscn 属性/头部解析(read_scene 现正确返回结构化属性)+ game_wait 轮询等待(pollWaitCondition),2597 测试 |
v0.18.0 | 2026-06-10 | 工具合并(39→27 MCP 工具)+ LEGACY 兼容模式 + manage_tools 迁移 + notifyToolsChanged |
v0.17.1 | 2026-06-08 | 五维审查 P0+P1 全量修复 — tscn 死代码删除 527 行 + core/tools 解耦 + animation-ops +38 测试 + EditorExecutor +16 测试 + 安全加固,2252 测试 |
v0.17.0 | 2026-06-07 | 审查修复 9 项(4C+5I/A)— tscn 编辑正确性 + 确认令牌截断保护 + 字符串 UID + 安全加固,2023 测试 |
v0.16.0 | 2026-05-31 | 审查驱动质量提升 — ToolDispatcher 提取 + 87 次提交 + merge_scene + 项目脚手架 + 智能类型转换 + 1638 测试 |
v0.15.1 | 2026-05-27 | Godot 4.6 editor plugin 兼容性修复 |
v0.15.0 | 2026-05-27 | 6 代理并行审查(14 CRITICAL 修复)+ deny-by-default 安全 + Bridge 录制 + ESLint + 1509 测试 |
v0.14.0 | 2026-05-24 | 7 轴全维度审查(8 CRITICAL 修复)+ IK 框架 MVP + Vitest 迁移 1257 测试 |
v0.13.0 | 2026-05-23 | Bridge 安全加固 20 项 + requestId 取模 + CSS Grid + EditorConnection 重连上限 |
v0.12.0 | 2026-05-23 | 迭代 URL 解码防路径遍历 + verify_delivery 4 维度验证 + dev_loop acceptance |
v0.11.1 | 2026-05-22 | Bridge TCP 绑定 127.0.0.1 + 密钥文件读后即删 + opsErrorResult isError 修复 |
v0.11.0 | 2026-05-22 | CSS Flexbox 布局翻译层 + GDScript Lint 规则引擎 + 路径遍历防护增强 |
v0.10.1 | 2026-05-21 | Bridge TCP 绑定本地地址 + 密钥文件生命周期管理 + opsErrorResult 修复 |
v0.10.0 | 2026-05-19 | 场景实例化 + 编辑器实时同步 + 代码优化重构(124 工具) |
v0.9.0 | 2026-05-16 | 批量工具 + UI 工具 + 录制系统 + 确认令牌 + Read-Only/Lite 模式(118 工具) |
v0.8.0 | 2026-05-13 | 双模式架构 + 测试框架 + 粒子/导航/AnimationTree(96 工具) |
v0.7.0 | 2026-05-08 | 安全加固 + 输入转义 + 类型安全 + tscn-parser 修复 |
v0.6.0 | 2026-05-03 | 音频播放控制 4 工具 + TileMap 编辑 8 工具 |
v0.5.0 | 2026-05-02 | 信号控制 + 物理查询 + 3D 创建 + 导航寻路(8 工具) |
v0.4.0 | 2026-05-01 | 版本检测 + validate_scripts + search_and_replace + 截图稳定性 |
v0.3.0 | — | edit_script + batch_add_nodes + validate_project + import_resources |
v0.2.0 | — | read_scene + read/write_script + query_scene_tree + MCP Resources |
v0.1.0 | — | 项目管理 + 场景操作 + 执行控制 + 截图 + execute_gdscript |
https://github.com/youichi-uda/godot-mcp-pro README(含其自带竞品对比表),抓取 2026-06-27
↩GDAI MCP,数据转引自 godot-mcp-pro 对比表,2026-06-27
↩https://github.com/Coding-Solo/godot-mcp,抓取 2026-06-27
↩https://github.com/yanhuifair/Godot-MCP,抓取 2026-08-19(工具数 386 为
↩grep -c "registry.register(" src/tools/register.ts实测)该仓库 README 声称「freeze/step/screenshot No other public Godot MCP does this」——与事实不符:本项目的
↩playtest.freeze/step_until(结构化条件步进)与 satelliteoflove/godot-mcp(2025-12 起)的 deterministic playtesting 均早于该声明,供读者自行核对。
Available Tools
26 toolsanalysisARead-onlyIdempotent
理解层静态分析(零 Godot 依赖)。action=signal_map 列全项目信号连接(.tscn [connection] 声明 + .gd 代码 connect/emit 引用,两来源分开标注);action=impact_check 改动前影响面评估——改信号列出全部连接方/发射方/监听方,改脚本列出引用它的场景与节点,改场景列出其连接/脚本/被实例化处。盲区诚实标注:运行时动态信号名/autoload 间连接不可见。
Inputs: action (required), project_path (required), limit, scene, +3 more.
animationADestructive
查询、控制和编辑动画。查询: list_players, get_info, get_details, get_keyframes。播放: play, stop, seek, blend。编辑: create, delete, update_props, add_track, remove_track, add_keyframe, remove_keyframe, update_keyframe。运行时操作,仅影响当前执行上下文。如需持久化,请编辑 .tscn 文件。
Inputs: action (required), args, step, time, +30 more.
animation_trackADestructive
动画轨道与关键帧操作。轨道: add_track, remove_track。关键帧: add_keyframe, remove_keyframe, update_keyframe。曲线: set_curve。运行时操作,仅影响当前执行上下文。如需持久化,请编辑 .tscn 文件。
Inputs: action (required), time, value, in_handle, +11 more.
animtreeA
查询、控制和编辑 AnimationTree。支持创建节点、添加状态、添加转换、设置混合参数、播放状态、编辑状态属性。运行时操作,仅影响当前执行上下文。如需持久化,请编辑 .tscn 文件。
Inputs: action (required), name, value, parent, +14 more.
audioA
音频操作。play: 播放(支持 AudioStreamPlayer/2D/3D)。stop: 停止。set_param: 设置参数(volume_db/pitch_scale/bus)。query: 查询播放状态。运行时操作,仅影响当前执行上下文。如需持久化,请编辑 .tscn 文件。
Inputs: action (required), bus, param, value, +7 more.
auditARead-onlyIdempotent
操作审计日志查询(G3)。action=get_log 读 {project}/.godot/mcp_audit.jsonl 统计回放(操作计数/风险高亮/最近条目/时间范围);action=suggest_rollback 对指定条目给诚实回滚建议(create 类可删/project.godot before_values/其余靠 Git)。write/destructive 操作经 audit after middleware 自动落盘(changed_files 为项目相对路径,PII 护栏)。
Inputs: action (required), limit, since, entry_index, +1 more.
confirm_and_executeA
Execute a previously blocked tool using a confirmation token. Use this when a tool returns a confirmation_token.
Inputs: token (required).
cppAIdempotent
GDExtension (C++) 脚手架生成。scaffold_gdextension: 在 project_path 下生成完整可编译的 godot-cpp GDExtension 工程骨架(src/类.cpp/.h + register_types + SConstruct + .gdextension + .gitignore + README),不联网/不编译,对齐 godot-cpp 官方 example。
Inputs: action (required), project_path (required), force, class_name, +2 more.
docsBRead-onlyIdempotent
Query Godot class documentation: get_class_info, search_classes, find_method, get_inheritance.
Inputs: action (required), limit, query, class_name, +2 more.
gameB
游戏桥接操作(游戏运行时经 bridge 通信):安装/卸载 bridge、查询场景树/节点属性/截图、写入属性/调方法、模拟输入、等待条件、确定性 playtest(seed/锁步长/单步/快照)、freeze 控制、monitor 属性采样、watch 信号记录、UI 元素发现与点击、弱网注入、项目自定义命令。完整用法见规则文档(或 help 工具)。
Inputs: action (required), op, path, port, +29 more.
godot_get_contextARead-onlyIdempotent
一次返回会话全景(模式/项目/连接/场景快照/最近调用统计/工具组/推荐 workflow/规则/性能),减少反复探路。headless 模式 scene=null。
Inputs: project_path, include_scene, include_performance.
helpARead-onlyIdempotent
获取任意工具的完整文档。可用工具名:analysis, android, animation, animation_track, animtree, asset, audio, audit, blender, confirm_and_execute, cpp, csv_to_resources, dap, debug, docs, editor, engine, game, godot_advanced_tool, godot_get_context, godot_list_dynamic_routes, godot_list_instances, godot_select_instance, help, load_skill, manage_tools, material, nav, particles, physics, profiler, project, qa, runtime, runtime_assert, scene, screenshot, script, self_update, signal, testing, tilemap, translation, ui, uid, validation, workflow。传 tool_name 获取该工具的详细用法、参数、action 列表。拼写纠错自动提示最接近的工具名。
Inputs: tool_name (required).
load_skillA
从本地知识库(GodotPrompter/gd-agentic 等)按关键词检索 SKILL.md。两级检索:name/description 高精度→全文 fallback。返回带来源标注(source/path)和相关性 score 的匹配。缺失库进 missing_libraries 不报错。
Inputs: query (required), limit, libraries.
materialA
Material and shader operations. Read: read. Write: set_params, create, save, load. Shader: shader_read, shader_write, shader_load_file, shader_save_file, shader_list_templates, shader_apply_template. 运行时操作,仅影响当前执行上下文。如需持久化,请编辑 .tscn 文件。
Inputs: action (required), code, params, file_path, +8 more.
particlesAIdempotent
创建 GPUParticles2D/3D 节点、设置发射/处理参数、加载预设效果、设置粒子材质。运行时操作,仅影响当前执行上下文。如需持久化,请编辑 .tscn 文件。运行时操作,仅影响当前执行上下文。如需持久化,请编辑 .tscn 文件。
Inputs: action (required), name, amount, parent, +18 more.
profilerARead-onlyIdempotent
性能分析工具。snapshot: 快照(FPS/内存/绘制调用/物理统计)。start/stop: 开始/停止分析会话。get_data: 收集帧级数据,含多维度采样、p99百分位、趋势退化检测、内存趋势、渲染统计。get_active_processes: 遍历场景树查找有 _process/_physics_process 的节点。get_signal_connections: 列出子树所有信号连接。运行时操作,仅影响当前执行上下文。如需持久化,请编辑 .tscn 文件。
Inputs: action (required), top, sort, seconds, +8 more.
projectC
搜索 Godot 项目、获取项目信息、列出文件、读取配置、创建项目、设置项目规则。
Inputs: action (required), ci, key, tag, +19 more.
qaA
QA 测试套件编排:结构化测试规范 → 自动安装 bridge → 运行游戏 → 逐步执行 → 聚合报告 + 回归 diff。步骤类型:input/wait/wait_frames/freeze/unfreeze/step_until/snapshot/restore/set/call/watch_start|stop/monitor_start|stop/assert/screenshot/sleep;断言 8 种与各字段语义见 schema 字段 description。run 支持 mode:async 后台执行(qa status/cancel 管理)。报告落 ~/.godot-mcp/qa-reports/<run_id>.{json,md}。
Inputs: action (required), mode, spec, run_id, +5 more.
runtimeC
启动编辑器、运行/停止项目、获取调试输出、运行测试、获取 Godot 版本。
Inputs: action (required), speed, timeout, file_name, +9 more.
runtime_assertARead-onlyIdempotent
运行时断言:在运行中的游戏上验证节点状态/场景结构/屏幕文本/性能/截图对比。agent 可任意时刻调用,不必走 workflow.dev_loop。全部依赖 game-bridge(需先 game_bridge_install + 游戏运行中)。
Inputs: action (required), path, text, nodes, +8 more.
sceneCDestructive
场景操作。读取/创建: read_scene, create_scene, quick_scene。节点: add_node, batch_add_nodes, edit_node, remove_node。保存/资源: save_scene, load_sprite。查询: query_scene_tree, inspect_node。实例: instance_scene, set_instance_property, detach_instance。
Inputs: action (required), name, save, type, +26 more.
screenshotBRead-onlyIdempotent
Screenshot capture and image analysis handoff. capture: capture a Godot scene screenshot in headless mode (experimental). analyze: return the image as MCP image content (base64) for the client vision capability to examine — returns image data, NOT a text description.
Inputs: action (required), scene, detail, image_a, +18 more.
scriptADestructive
脚本操作。读写: read_script, write_script。编辑: edit_script(行号/search_and_replace)。执行: execute_gdscript(⚠️ 沙箱仅防误操作,不可用于不可信输入。高安全场景请用 ALLOW_EXECUTE_GDSCRIPT=false 或容器隔离)。⚠️ write_script/edit_script 写入 .gd 前也走沙箱扫描(防 @tool 脚本加载即执行等已知危险 API 模式(清单不列举,防沙箱边界被侦察);与 execute_gdscript 同威胁面)。测试: generate_test, create_test_scene。批量替换: project_replace。💡 execute_gdscript 最佳实践:分步执行、每步验证(把复杂逻辑拆成小块逐一跑,每步用 read_script/edit_script 迭代,避免一次性大脚本出错难定位)。
Inputs: action (required), code, search, content, +17 more.
signalA
信号操作。connect/disconnect: 连接/断开信号。emit: 发射信号(参数仅基本类型)。list: 列出节点可用信号。运行时操作,仅影响当前执行上下文。如需持久化,请编辑 .tscn 文件。
Inputs: action (required), args, flags, node_path, +6 more.
validationA
运行验证、分析错误、验证项目/脚本、导入资源。一键 headless 运行 + 错误分析,或按需单项检查。
Inputs: action (required), scene, scope, output, +14 more.
workflowC
Development workflow tools. dev_loop: execute GDScript with optional validation, bridge queries, and state saving. scene_snapshot: capture structured scene tree snapshot. batch_validate: validate multiple GDScript files at once.
Inputs: action (required), code, bridge, verify, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Several tool pairs have overlapping responsibilities: animation and animation_track both manage tracks/keyframes, profiler.get_signal_connections overlaps analysis.signal_map and signal.list, and runtime_assert duplicates query capabilities of game. The 'game' tool also subsumes many runtime/bridge operations that could be confused with runtime and qa.
Most tools are single lowercase nouns (project, scene, script), but several use snake_case verb phrases (godot_get_context, runtime_assert, confirm_and_execute), and animation_track is an inconsistent descriptor next to animation. There is no consistent verb_noun pattern across the set.
At 26 tools, the set is on the heavy side, with several tools that could be consolidated (animation and animation_track, game and runtime_assert). Still, each tool reflects a substantial Godot subdomain, so the count is not egregious.
The server covers most major Godot workflows: project, scene, scripting, runtime, docs, animation, audio, materials, particles, signals, profiling, static analysis, QA, and C++ scaffolding. However, some areas referenced by help (asset, ui, physics, tilemap) are not exposed as actual tools, and there are no project-level delete/export operations.
Maintenance
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
An MCP server that gives your AI access to the source code and docs of all public github repos
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that gives AI assistants direct control over Godot 4 game development projects. It enables launching the editor, running projects, creating and editing scenes, writing GDScript, and inspecting assets through natural language commands.444MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to directly run, inspect, modify, and debug Godot game development projects through 110+ tools covering scenes, scripts, resources, runtime debugging, and asset management.333MIT
- AlicenseCqualityCmaintenanceAn MCP server providing AI assistants with 149 tools to fully control the Godot game engine, including runtime code execution, scene manipulation, physics, audio, networking, animation, and more.10098 npm515MIT
- AlicenseNot gradedqualityCmaintenanceA security-first MCP server and Godot editor addon enabling AI agents to observe and control Godot games through bounded, permission-gated tools for debugging, input automation, and project editing.MIT