Godot MCP

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


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

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

简介

Godot MCP 允许 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

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 文件。

Godot MCP 快速上手指南

Godot MCP 是一个基于 Model Context Protocol (MCP) 的服务器工具，它允许 AI 助手（如 Claude Code、Cursor、Cline）直接与 Godot 游戏引擎交互。通过该工具，AI 可以启动编辑器、运行项目、捕获调试输出、管理场景节点以及处理资源 UID，从而实现更智能的代码生成和自动化调试。

环境准备

在开始之前，请确保您的系统满足以下要求：

• Godot 引擎：已安装 Godot Engine（推荐最新稳定版）。
• Node.js：版本需 >= 18.0.0。
• npm：随 Node.js 一同安装。
• MCP 兼容客户端：如 Claude Code、Cursor 或 Cline 等支持 MCP 协议的 AI 开发工具。

安装步骤

Godot MCP 无需手动克隆仓库即可使用，可通过 npx 直接运行。根据您的 AI 客户端选择以下一种配置方式：

方式一：Claude Code (命令行配置)

在终端中运行以下命令将 Godot MCP 添加到 Claude Code：

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

如果需要指定 Godot 路径或开启调试模式：

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

(请将 /path/to/godot 替换为您实际的 Godot 可执行文件路径)

方式二：Cursor (图形界面或配置文件)

方法 A：通过 UI 设置

1. 打开 Cursor Settings > Features > MCP。
2. 点击 + Add New MCP Server。
3. 填写表单：
   • Name: godot
   • Type: command
   • Command: npx @coding-solo/godot-mcp
4. 点击 "Add" 并刷新列表。

方法 B：项目级配置 在项目根目录创建 .cursor/mcp.json 文件，内容如下：

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

方式三：Cline (配置文件)

编辑 Cline 的 MCP 设置文件 (~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json Windows 用户路径类似)，添加以下配置：

{
  "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"
      ]
    }
  }
}

基本使用

配置完成后，重启您的 AI 客户端。您现在可以在对话中直接使用自然语言指令控制 Godot。

使用示例：

1. 检查环境与版本

   "检查当前安装的 Godot 版本，并列出当前目录下的所有 Godot 项目。"

2. 运行与调试

   "以调试模式运行当前的 Godot 项目，并捕获控制台输出的错误信息。" "停止正在运行的项目实例。"

3. 场景与节点管理

   "创建一个新场景，根节点类型为 'Node2D'。" "在当前场景中加载一个 Sprite2D 节点，并将 'player.png' 设置为纹理。" "将当前的 3D 场景导出为 MeshLibrary 资源以便用于 GridMap。"

4. 高级操作 (Godot 4.4+)

   "获取 'res://scenes/main.tscn' 文件的 UID，并更新项目中所有对该资源的引用。"

提示：若 AI 无法自动找到 Godot 可执行文件，请在配置中添加 GODOT_PATH 环境变量指向您的 Godot 安装路径。