Godot MCP Enhanced

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

给 AI(Claude Code、Cursor、CodeBuddy 等 MCP 客户端)一个能真正读、写、跑、验证 Godot 项目的 工具层:43 个 MCP 工具(merged,共 235 个 action;完整清单见 capability-matrix)覆盖场景/脚本/UI/动画/物理/粒子/导航/音频/测试/导出/3D 参数化资产(asset:11 shape + 路径阵列 + batch 原子 undo),三层架构 (headless + editor + game bridge)+ 路径白名单 / 注入防御 / sandbox 安全体系。

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

与同类方案对比

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

[^p1]: https://github.com/youichi-uda/godot-mcp-pro README(含其自带竞品对比表),抓取 2026-06-27 [^p2]: GDAI MCP,数据转引自 godot-mcp-pro 对比表,2026-06-27 [^p3]: https://github.com/Coding-Solo/godot-mcp,抓取 2026-06-27

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

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

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

安全体系

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

• 路径访问控制 — ALLOWED_PROJECT_PATHS 白名单(deny-by-default),防 junction / 符号链接绕过
• 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,详见下方「匿名遥测」段)

匿名遥测（默认关闭）

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)。严格零外传需防火墙、NO_PROXY=registry.npmjs.org 或 readOnly 模式拒整工具。详见 docs/telemetry.md。

代理环境变量:update-checker 的 npm registry fetch 遵守 HTTP_PROXY/HTTPS_PROXY/NO_PROXY 环境变量（Node 默认 trustEnv）。企业代理环境下请求经代理；完全阻断可设 NO_PROXY=registry.npmjs.org 或防火墙规则。刻意不设 trustEnv: false——那会切断合法企业代理用户的更新检查。

⚠️ 诚实披露 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 既无约束也无声明"。

核心能力

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

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

动态 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 完整编译(含跨文件依赖),捕获 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 少踩坑、按纪律走。

工具一览

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

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

执行工具

验证工具

动态执行工具

项目工具

场景工具

脚本工具

运行时操作工具

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

音频播放控制工具（运行时）

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

TileMap 编辑工具（运行时）

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

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

API 文档工具

材质与着色器工具（运行时）

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

Game Bridge 工具

工作流工具

动画工具（运行时）

性能分析工具（运行时）

3D 空间工具

测试与导出工具

粒子系统工具（运行时）

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

导航工具（运行时）

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

AnimationTree 工具（运行时）

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

IK 框架工具（运行时）

验证交付工具

游戏设计工具

代码模板工具

UI 布局工具（运行时）

录制工具

编辑器同步工具

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

MCP 资源（Resources）

AI 客户端可通过 godot:// 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 配置（零额外配置）。

✅ 协议层实测通过（43 工具全发现、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 客户端 + 写入配置

首次使用

连接 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 跳过。

环境变量

⚠️ BREAKING(G7):默认 profile 从 full 改 basic(对齐 GoPeak compact,省 AI context window)。升级后 tools/list 只暴露 basic(lite 9 组:core/bridge/animation/audio/signal/visual/code/test/profiler)。回退全量 41 工具:GODOT_MCP_PROFILE=full;或 AI 运行时 manage_tools activate 动态扩容(无需重启)。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/ 中查找对应版本。

手动配置（高级用户）

致谢

• godot-mcp — 原始项目，本项目基于其二次开发（Copyright © 2025 Solomon Elias，MIT，见 LICENSE）
• Hastur Operation Plugin — 动态 GDScript 执行和结构化输出的灵感来源
• Claude Code Game Studios — 借鉴了以下功能概念：
  • 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.sh
  • GDD 标准 → validate_gdd 8 章节游戏设计文档结构校验，对标 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 >= 18
• GUT 插件（用于 run_tests 工具）

许可证

MIT — 含上游 Coding-Solo/godot-mcp 版权（Copyright © 2025 Solomon Elias）。

路线图

项目方向与里程碑(M1 定位与声量 / M2 健壮性 P0 / M3 安全 P1 / M4 功能补齐 P2)见 ROADMAP.md。

更新日志

完整变更记录见 CHANGELOG.md。