Godot MCP

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

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

一个用于与 Godot 游戏引擎交互的 Model Context Protocol (MCP) 服务器。

简介

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

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

特性

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

要求

• 您的系统上安装了 Godot Engine
• Node.js 和 npm
• 支持 MCP 的 AI 助手 (Cline, Cursor 等)

安装和配置

步骤 1: 安装和构建

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

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

步骤 2: 使用您的 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 设置 > Features > MCP
2. 单击 + Add New MCP Server 按钮
3. 填写表格：
   • Name: godot (或您喜欢的任何名称)
   • Type: command
   • Command: node /absolute/path/to/godot-mcp/build/index.js
4. 单击 "Add"
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 服务器。 您可以使用如下提示：

"启动位于 /path/to/project 的项目的 Godot 编辑器"

"运行我的 Godot 项目并显示任何错误"

"获取有关我的 Godot 项目结构的信息"

"分析我的 Godot 项目结构并提出改进建议"

"帮助我调试我的 Godot 项目中的这个错误：[粘贴错误]"

"编写一个具有二段跳和滑墙功能的角色控制器的 GDScript"

"在我的 Godot 项目中创建一个带有 Player 节点的新场景"

"将 Sprite2D 节点添加到我的玩家场景并加载角色纹理"

"导出我的 3D 模型作为 MeshLibrary 以用于 GridMap"

"为我游戏的主菜单创建一个带有按钮和标签的 UI 场景"

"获取我的 Godot 4.4 项目中特定脚本文件的 UID"

"升级到 4.4 后更新我的 Godot 项目中的 UID 引用"

实现细节

架构

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 设置中启用 (Settings > MCP)
• MCP 工具只能使用 Agent 聊天配置文件运行 (Cursor Pro 或 Business 订阅)
• 使用 "Yolo Mode" 自动运行 MCP 工具请求

许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。