godot-mcp-enhanced

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 / 工具数 / 价格均可能变化,详见各项目仓库)。

"—" 表示该项目公开 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;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/项目待办.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（只读契约/防穿越）

匿名遥测（默认关闭）

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 既无约束也无声明"。

核心能力

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

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

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 131+write 115+destructive 10+process 16)。对比竞品统一用「顶层工具数」口径。两个数字均由 npm run build-matrix 从代码自动生成,CI 漂移检测守护。

执行工具

验证工具

动态执行工具

项目工具

场景工具

脚本工具

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

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

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

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

TileMap 编辑工具（运行时）

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

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

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

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

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

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。

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

动画工具（运行时）

性能分析工具（运行时）

3D 空间工具

测试与导出工具

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

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

导航工具（运行时）

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

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

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

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

验证交付工具

游戏设计工具

代码模板工具

UI 布局工具（运行时）

录制工具

编辑器同步工具

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

⚠️ 运行时工具(物理 / 动画 / 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 配置（零额外配置）。

✅ 协议层实测通过（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 跳过。

环境变量

⚠️ 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

常驻守护进程模式（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 子命令，勿混淆）：

客户端配置（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.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 >= 20（与 package.json engines 一致）
• GUT 插件（用于 run_tests 工具）

许可证

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

路线图

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

更新日志

完整变更记录见 CHANGELOG.md。