用途
godot-mcp 是一个面向 Godot 游戏引擎的 Model Context Protocol（MCP）服务器，用于让 AI 智能体与 Godot 项目进行交互。通过该服务器，AI 智能体可以启动 Godot 编辑器、运行项目、捕获调试输出并控制项目执行，从而建立直接反馈循环，帮助智能体判断代码在真实 Godot 项目中的运行效果，提升代码生成和调试协助的质量。
主要能力
- 启动 Godot 编辑器：为指定项目打开 Godot 编辑器。
- 运行 Godot 项目：以调试模式执行 Godot 项目。
- 捕获调试输出：获取控制台输出和错误消息。
- 控制执行：以编程方式启动和停止 Godot 项目。
- 获取 Godot 版本：检索已安装的 Godot 版本。
- 列出 Godot 项目：在指定目录中查找 Godot 项目。
- 项目分析：获取项目结构的详细信息。
- 场景管理：
- 创建具有指定根节点类型的新场景；
- 向现有场景添加具有可自定义属性的节点；
- 将精灵和纹理加载到 Sprite2D 节点；
- 将 3D 场景导出为供 GridMap 使用的 MeshLibrary 资源；
- 保存场景，并支持创建变体。
- UID 管理（适用于 Godot 4.4+）：
- 获取特定文件的 UID；
- 通过重新保存资源来更新 UID 引用。
使用方式
前置条件
- 系统已安装 Godot 引擎。
- Node.js（>=18.0.0）和 npm。
- 一个支持 MCP 的 AI 智能体。
满足上述条件后，重启 Claude Code 即可使用 Godot MCP 工具。
配置
支持通过环境变量配置。
Cline：添加到 Cline MCP 设置文件（~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）。
Cursor UI：
- 进入 Cursor Settings > Features > MCP；
- 点击 “+ Add New MCP Server” 按钮；
- 填写表单：Name: godot，Type: command，Command:
npx @coding-solo/godot-mcp； - 可能需要点击 MCP 服务器卡片右上角的刷新按钮以填充工具列表。
项目级配置：在项目目录中创建 .cursor/mcp.json 文件。
其他 MCP 兼容客户端：可使用以下配置：
Command: npx @coding-solo/godot-mcp
环境变量
可将 MCP 客户端指向 build/index.js，而不是使用 npx。
工作原理
Godot MCP 服务器对复杂操作采用捆绑的 GDScript 方案：
- 直接命令：启动编辑器或获取项目信息等简单操作直接使用 Godot 内置 CLI 命令。
- 捆绑操作脚本：创建场景或添加节点等复杂操作使用单个全面的 GDScript 文件（
godot_operations.gd）处理所有操作。该捆绑脚本接受操作类型和参数（JSON 格式），无需为每个操作生成临时文件，即可灵活动态地执行操作。
适用场景
适用于需要 AI 智能体直接与 Godot 游戏引擎交互的场景，例如借助 AI 生成或调试 Godot 项目代码、自动化管理场景和资源、在开发过程中获取实时调试反馈等。
限制与排错
- 找不到 Godot：设置
GODOT_PATH环境变量为 Godot 可执行文件路径。 - 连接问题：确保服务器正在运行，并重启 AI 助手。
- 项目路径无效：确保路径指向包含
project.godot文件的目录。 - 构建问题：确保已通过运行
npm install安装所有依赖。 - 在 Cursor 设置（Settings > MCP）中确认 MCP 服务器已显示并启用。
- MCP 工具只能使用 Agent 聊天配置文件（Cursor Pro 或 Business 订阅）运行。
- 使用 “Yolo Mode” 可自动运行 MCP 工具请求。
许可
本项目基于 MIT 许可证发布，详见 LICENSE 文件。
