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(action capture)截图给你看现在的样子;
- 迭代 — 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,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 放行(本地信任场景,签名校验仍兜底);例外(2026-10-13 安全收紧,审查 M-2):AI 可控的工具参数 godot_path override 在白名单未配置时一律拒绝——防"cwd 内写伪造 --version 签名的二进制再经参数指向它"的执行链(GODOT_PATH env、godot-paths.json 与自动发现链不受影响);多用户/不可信环境显式列可信路径
- 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/项目待办.md frontmatter 计数优先、复选框计数兜底）与最近开发日志,面板内浏览日志正文与看板分节摘要,并提供 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 触发合成事件