godot-mcp

Godot MCP

通过 MCP 使用 AI 控制 Godot 4——场景操作、3D 导入、GPU 粒子、程序化纹理、HTML5 导出。确定性游戏测试：冻结游戏时钟，注入模拟/手柄/鼠标输入，逐帧运行直至满足条件，并将实时游戏状态读取为结构化 JSON。游戏构建器：用自然语言描述游戏，即可生成可玩的 GDScript 并导出。发布到 itch.io 和 Steam。95+ 个工具、77 项测试、NSIS 桌面安装程序。

---

快速安装

git clone https://github.com/sandraschi/godot-mcp
cd godot-mcp
just bootstrap       # install deps
just serve           # start server (10993)
just web             # open dashboard (10992)

所有选项（MCPB、开发环境设置、裸机 PC）请参阅 INSTALL.md。

---

功能

• 游戏构建器 — design_game -> generate_game_logic -> generate_game_tests -> generate_dialogue -> 导出。通过 gdlint + godot --check-only 验证，并由 LLM 自动修复。教程
• 程序化纹理 — godot_generate_procedural_texture：渐变、噪声、棋盘格、纯色。无需外部资源。
• 确定性游戏测试 — 冻结游戏时钟、逐帧运行、运行至满足 GDScript 条件、注入模拟/手柄/鼠标/文本输入。三阶段实现方案受 satelliteoflove/godot-mcp 启发。
• 结构化游戏状态 — godot_state_digest 通过 _mcp_state() 约定或自动收集的属性，将实时节点状态读取为 JSON。比完整场景树转储更省资源。
• 引擎控制 — 30 个桥接工具：导入 STL/GLB/OBJ、粒子、摄像机、光照、动画、视口捕获、输入模拟、场景节点管理。
• 动画关键帧编辑器 — 查询轨道中的单个关键帧、插入/移除关键帧、设置插值。
• TileMap/GridMap 编辑 — 直接读取和写入单元格数据（绕过 base64 .tscn 序列化）。
• 性能分析器 — 14 项引擎指标，支持自动采样和峰值检测（>2 个标准差）。
• 网格验证 — 扫描 NaN 顶点、退化三角形、零法线。
• 3D Gaussian Splat 导入 — 使用自定义公告板式 Gaussian 着色器导入 .ply 和 .spz 文件（每个 splat 独立缩放、SH DC 颜色）。
• 发布 — itch_ops 和 steam_ops 集合工具，用于 itch.io Butler 和 SteamPipe。跨仓库舰队流水线。
• GDScript 验证 — 两轮验证（gdlint 风格检查 + godot 编译），并由 LLM 修复。
• 插件生态 — 可从 /plugins 页面安装 7 个社区插件。
• LLM 检测 — 自动探测 GPU，并根据 VRAM 级别推荐模型。默认使用 gemma4:12b。
• 示例游戏 — Vibecoder Runner，包含 10 种 AI 主题敌人。

可以做什么

just gb-demo "A 2D runner where you collect stars and avoid spikes"
just bridge-test                          # check engine connection
just demo-run vibecode                    # play sample game
just gb-preview                           # preview latest HTML5 export

文档

文档	内容
安装	所有安装方式
配置	环境变量、设置
工具参考	所有 90+ 个 MCP 工具
游戏测试规范	确定性游戏测试架构
演示脚本	游戏测试、性能分析、场景检查、splat 导入演示
游戏构建器教程	从提示词到游戏的完整演示
Godot 生态	插件、gdtoolkit、舰队流水线
故障排除	常见问题
API 参考	REST 端点
开发	贡献指南、本地环境设置

要求

• Godot 4.4+（用于引擎桥接工具）— just install-godot 或 godotengine.org
• Python 3.13+ + uv — winget install astral-sh.uv
• Bun — winget install oven-sh.bun
• Ollama（可选，用于游戏构建器）— winget install Ollama.Ollama，然后运行 ollama pull gemma4:12b
• Rust（可选，用于 NSIS 构建）— rustup.rs

许可证

MIT — 详见 LICENSE。