Godot MCP

Godot MCP

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


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

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

简介

Godot MCP 可让 AI Agent 启动 Godot 编辑器、运行项目、捕获调试输出并控制项目执行。这个直接反馈循环有助于 Agent 了解真实 Godot 项目中哪些功能有效、哪些无效，从而更好地生成代码并提供调试帮助。

功能

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

要求

• 系统中已安装 Godot Engine
• Node.js（>=18.0.0）和 npm
• 支持 MCP 的 AI Agent

快速开始

Claude Code

claude mcp add godot -- npx @coding-solo/godot-mcp

完成。重启 Claude Code 后即可使用 Godot MCP 工具。

使用环境变量：

claude mcp add godot -e GODOT_PATH=/path/to/godot -e DEBUG=true -- npx @coding-solo/godot-mcp

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["@coding-solo/godot-mcp"],
      "env": {
        "DEBUG": "true"
      },
      "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"
      ]
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["@coding-solo/godot-mcp"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["@coding-solo/godot-mcp"],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "DEBUG": "true"
      }
    }
  }
}

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

架构

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

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

捆绑脚本接受以 JSON 表示的操作类型和参数，因此可以灵活、动态地执行操作，无需为每项操作生成临时文件。

故障排除

• 未找到 Godot：将 GODOT_PATH 环境变量设置为 Godot 可执行文件的路径
• 连接问题：确保服务正在运行，并重启 AI 助手
• 无效的项目路径：确保路径指向包含 project.godot 文件的目录
• 构建问题：运行 npm install，确保安装了所有依赖项

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。