Godot MCP

                           (((((((             (((((((                          
                        (((((((((((           (((((((((((                      
                        (((((((((((((       (((((((((((((                       
                        (((((((((((((((((((((((((((((((((                       
                        (((((((((((((((((((((((((((((((((                       
         (((((      (((((((((((((((((((((((((((((((((((((((((      (((((        
       (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((      
     ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((    
    ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((    
      (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((     
        (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((       
         (((((((((((@@@@@@@(((((((((((((((((((((((((((@@@@@@@(((((((((((        
         (((((((((@@@@,,,,,@@@(((((((((((((((((((((@@@,,,,,@@@@(((((((((        
         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((        
         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((        
         (((((((((@@@,,,,,,,@@((((((((@@@@@((((((((@@,,,,,,,@@@(((((((((        
         ((((((((((((@@@@@@(((((((((((@@@@@(((((((((((@@@@@@((((((((((((        
         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((        
         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((        
         @@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@        
         ((((((((( @@@(((((((((((@@(((((((((((@@(((((((((((@@@ (((((((((        
         (((((((((( @@((((((((((@@@(((((((((((@@@((((((((((@@ ((((((((((        
          (((((((((((@@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@(((((((((((         
           (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((          
              (((((((((((((((((((((((((((((((((((((((((((((((((((((             
                 (((((((((((((((((((((((((((((((((((((((((((((((                
                        (((((((((((((((((((((((((((((((((                       
                                                                                

                          /$$      /$$  /$$$$$$  /$$$$$$$ 
                         | $$$    /$$$ /$$__  $$| $$__  $$
                         | $$$$  /$$$$| $$  \__/| $$  \ $$
                         | $$ $$/$$ $$| $$      | $$$$$$$/
                         | $$  $$$| $$| $$      | $$____/ 
                         | $$\  $ | $$| $$    $$| $$      
                         | $$ \/  | $$|  $$$$$$/| $$      
                         |__/     |__/ \______/ |__/       

一个用于与 Godot 游戏引擎交互的模型上下文协议 (MCP) 服务器。

简介

Godot MCP 使 AI 助手能够启动 Godot 编辑器、运行项目、捕获调试输出并控制项目执行——所有这些都通过一个标准化的接口完成。

这种直接的反馈循环有助于像 Claude 这样的 AI 助手理解在真实的 Godot 项目中什么有效，什么无效，从而提高代码生成和调试辅助的质量。

特性

• 启动 Godot 编辑器：打开特定项目的 Godot 编辑器
• 运行 Godot 项目：以调试模式执行 Godot 项目
• 捕获调试输出：获取控制台输出和错误信息
• 控制执行：以编程方式启动和停止 Godot 项目
• 获取 Godot 版本：检索已安装的 Godot 版本
• 列出 Godot 项目：在指定目录中查找 Godot 项目
• 项目分析：获取有关项目结构的详细信息
• 场景管理：
  • 使用指定的根节点类型创建新场景
  • 向现有场景添加具有自定义属性的节点
  • 将精灵和纹理加载到 Sprite2D 节点中
  • 将 3D 场景导出为 MeshLibrary 资源以供 GridMap 使用
  • 保存场景，并提供创建变体的选项
• UID 管理（适用于 Godot 4.4+）：
  • 获取特定文件的 UID
  • 通过重新保存资源更新 UID 引用

要求

• 在您的系统上安装 Godot 引擎
• Node.js 和 npm
• 支持 MCP 的 AI 助手（例如 Cline、Cursor 等）

安装和配置

第一步：安装和构建

首先，克隆仓库并构建 MCP 服务器：

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

第二步：与您的 AI 助手进行配置

选项 A：使用 Cline 配置

将以下内容添加到您的 Cline MCP 设置文件中（~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）：

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "DEBUG": "true"                  // Optional: Enable detailed logging
      },
      "disabled": false,
      "autoApprove": [
        "launch_editor",
        "run_project",
        "get_debug_output",
        "stop_project",
        "get_godot_version",
        "list_projects",
        "get_project_info",
        "create_scene",
        "add_node",
        "load_sprite",
        "export_mesh_library",
        "save_scene",
        "get_uid",
        "update_project_uids"
      ]
    }
  }
}

选项 B：使用 Cursor 配置

使用 Cursor UI：

1. 转到 Cursor 设置 > 功能 > MCP
2. 点击 + 添加新的 MCP 服务器 按钮
3. 填写表单：
   • 名称: godot（或任何你喜欢的名称）
   • 类型: command
   • 命令: node /absolute/path/to/godot-mcp/build/index.js
4. 点击“添加”
5. 您可能需要点击 MCP 服务器卡片右上角的刷新按钮以填充工具列表

使用特定于项目的配置：

在您的项目目录中创建一个名为 .cursor/mcp.json 的文件，内容如下：

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "DEBUG": "true"                  // Enable detailed logging
      }
    }
  }
}

步骤 3：可选环境变量

您可以使用以下环境变量来自定义服务器行为：

• GODOT_PATH: Godot 可执行文件的路径（覆盖自动检测）
• DEBUG: 设置为 "true" 以启用详细的服务器端调试日志

示例提示

配置完成后，您的 AI 助手将在需要时自动运行 MCP 服务器。您可以使用如下提示：

"Launch the Godot editor for my project at /path/to/project"

"Run my Godot project and show me any errors"

"Get information about my Godot project structure"

"Analyze my Godot project structure and suggest improvements"

"Help me debug this error in my Godot project: [paste error]"

"Write a GDScript for a character controller with double jump and wall sliding"

"Create a new scene with a Player node in my Godot project"

"Add a Sprite2D node to my player scene and load the character texture"

"Export my 3D models as a MeshLibrary for use with GridMap"

"Create a UI scene with buttons and labels for my game's main menu"

"Get the UID for a specific script file in my Godot 4.4 project"

"Update UID references in my Godot project after upgrading to 4.4"

实现细节

架构

Godot MCP 服务器使用捆绑的 GDScript 方法来处理复杂操作：

1. 直接命令: 简单操作如启动编辑器或获取项目信息直接使用 Godot 内置的 CLI 命令。
2. 捆绑操作脚本: 复杂操作如创建场景或添加节点使用一个全面的 GDScript 文件 (godot_operations.gd) 来处理所有操作。

这种架构提供了几个优点：

• 无需临时文件: 消除了对临时脚本文件的需求，保持系统整洁
• 简化代码库: 将所有 Godot 操作集中在一个（相对）组织良好的文件中
• 更好的可维护性: 使添加新操作或修改现有操作变得更加容易
• 改进的错误处理: 在所有操作中提供一致的错误报告
• 减少开销: 最小化文件 I/O 操作以提高性能

捆绑的脚本接受 JSON 格式的操作类型和参数，允许灵活且动态地执行操作，而无需为每个操作生成临时文件。

故障排除

• 找不到 Godot: 设置 GODOT_PATH 环境变量为您 Godot 可执行文件的路径
• 连接问题: 确保服务器正在运行并重启您的 AI 助手
• 无效的项目路径: 确保路径指向包含 project.godot 文件的目录
• 构建问题: 通过运行 npm install 确保安装了所有依赖项
• 对于 Cursor 特别注意:
• 确保 MCP 服务器出现在 Cursor 设置中并且已启用（设置 > MCP）
• MCP 工具只能使用 Agent 聊天配置文件运行（Cursor Pro 或 Business 订阅）
• 使用“Yolo 模式”自动运行 MCP 工具请求

许可证

此项目根据 MIT 许可证许可 - 详情请参阅 LICENSE 文件。