godot-mcp

📚 Godot MCP 项目介绍

一、项目概述

Godot MCP（Model Context Protocol 服务器）由 Coding‑Solo 发布，是一款桥接 AI 助手与 Godot 引擎的工具。通过 MCP 协议，它可以启动 Godot 编辑器、运行项目、捕获调试信息，并对项目结构和场景进行深度控制。

这一机制为 AI 助手（如 Claude、Cline、Cursor）提供真实的反馈循环，使其能够实际操作项目、调试问题并生成高质量 GDScript 代码。

---

二、核心功能与特性

1. 启动编辑器与运行项目
   支持通过命令行方式：

   • 启动指定路径下的 Godot 编辑器
   • 以调试模式运行项目
   • 捕获并返回控制台输出或错误信息

2. 项目结构获取与分析

   • 获取项目版本、目录结构和资源列表
   • 深入场景结构信息，包括节点树、属性、资源路径等

3. 场景与节点管理

   • 创建新场景（指定根节点类型）
   • 向现有场景添加节点并设置属性
   • 加载 Sprite2D 纹理、导出 MeshLibrary 用于 GridMap
   • 保存场景并支持生成场景变种

4. 调试与版本管理

   • 停止正在运行的项目
   • 获取并显示 Godot 引擎版本
   • （适用于 Godot 4.4+）获取文件 UID 并更新资源引用

5. 兼容多种 AI 辅助工具

   • 支持 Cline 和 Cursor：通过 MCP 设置文件、命令行集成 AI 助手工具

---

三、架构与实现亮点

• 单一 GDScript “操作脚本”
  所有复杂命令（如创建节点、场景导出等）由一个 godot_operations.gd 管理，避免逐个临时脚本生成，保证简洁高效，并减少磁盘 I/O 与出错可能。

• CLI 与 Script 结合机制
  简单命令直接通过 Godot CLI，复杂操作通过 GDScript 脚本，均由 MCP 标准传输 JSON 指令，结构统一，易扩展。

• 标准化响应结构
  所有操作返回统一格式：状态、结果内容、标准输出/错误，从而方便 AI 分析、学习与自动生成改动建议。

---

四、使用流程

1. 安装与构建

   git clone https://github.com/Coding-Solo/godot-mcp.git
   cd godot-mcp
   npm install
   npm run build
   

2. 配置 AI 工具

   • Cline：在 cline_mcp_settings.json 中添加对应 server 配置
   • Cursor：通过 Settings → Features → MCP 添加 node 指令

3. 运行与交互

   • AI 指令示例：

     • launch_editor：启动编辑器
     • run_project：执行项目并获取输出
     • create_scene / add_node：创建场景/节点
     • get_debug_output / stop_project：调试控制类指令
     • get_uid / update_project_uids：UID 管理

---

五、项目亮点总结

优势	描述
🌟 高自动化	AI 助手直接操控编辑器/项目，无需手动干预
🚫 无临时文件	使用 GDScript 单一入口，轻量高效
♻️ 支持版本 & UID	兼容 Godot 4.4+ 特性，能管理资源 UID
🛠️ 易扩展 & 易集成	MCP 标准便于新增功能，与多 AI 工具兼容

---

六、总结 🌈

Godot MCP 是一款强大且实用的工具，它为 AI 助手与 Godot 引擎搭建了一座桥梁。AI 可直接：

• 启动编辑器、运行项目、数据采集；
• 访问项目结构、脚本、场景、资源；
• 动态修改场景、节点、脚本；
• 进行调试、生成 GDScript 代码建议。

借助统一协议与 GDScript 操作脚本，它提供了清晰、标准、可扩展的自动化接口，对游戏开发者而言，是提升效率与智能化研发流程的利器。