Godot MCP

Godot MCP

功能全面的模型上下文协议（MCP）服务，可将 AI 助手与 Godot 游戏引擎无缝集成。

目录

• 什么是 Godot MCP？
• 功能
• 要求
• 安装
• 配置
• API 参考
• 项目架构
• 使用示例
• 只读模式
• 故障排除
• 常见问题
• 贡献
• 许可证

什么是 Godot MCP？

Godot MCP 通过提供标准化的模型上下文协议接口，搭建起 AI 助手与 Godot 游戏引擎之间的桥梁。这项强大的集成让 Claude、Cursor 和 Cline 等 AI 助手能够通过一系列全面的工具直接操作 Godot 项目。

核心价值

• 直接集成 Godot：以编程方式启动编辑器、运行项目并捕获调试输出
• 场景管理：通过 AI 命令创建、修改和管理 Godot 场景
• 实时反馈：AI 助手能够查看 Godot 的实际输出和错误，从而提供更好的帮助
• 跨平台兼容性：在 Windows、macOS 和 Linux 上均可无缝运行
• 安全操作：提供可选的只读模式，安全地分析项目
• 零配置：自动检测 Godot，并支持手动覆盖选项

工作原理

该服务充当 AI 助手与 Godot 之间的中间层，将自然语言命令转换为特定的 Godot 操作。当你要求 AI“创建一个带精灵的玩家场景”时，MCP 服务会：

1. 验证请求和项目结构
2. 执行相应的 Godot 操作
3. 返回详细的成功或错误反馈
4. 让 AI 理解结果并作出回应

这形成了一个强大的反馈循环，让 AI 助手能够从 Godot 的实际行为中学习，从而更准确地生成代码并协助调试。

功能

核心项目管理

• 🚀 启动 Godot 编辑器：打开指定项目的 Godot 编辑器
• ▶️ 运行 Godot 项目：以调试模式运行项目并实时捕获输出
• 🛑 控制执行：以编程方式启动和停止 Godot 项目
• 📊 捕获调试输出：获取完整的控制台输出和错误消息
• ℹ️ 系统信息：获取已安装的 Godot 版本和项目元数据
• 📁 项目发现：查找并列出指定目录中的 Godot 项目

高级场景管理

• 🎬 创建新场景：使用指定的根节点类型生成场景
• ➕ 添加节点：向现有场景插入节点，并自定义属性
• ✏️ 编辑节点属性：修改位置、缩放、纹理及其他节点属性
• 🗑️ 移除节点：移除不需要的节点，清理场景
• 🖼️ 加载精灵：自动将纹理加载到 Sprite2D 节点
• 🧱 导出 MeshLibrary：将 3D 场景转换为供 GridMap 使用的 MeshLibrary 资源
• 💾 保存场景变体：创建场景副本并管理场景版本

Godot 4.4+ UID 管理

• 🔗 获取文件 UID：检索项目资源的唯一标识符
• 🔄 更新 UID 引用：在项目升级期间维护正确的资源链接

安全与防护

• 🔒 只读模式：在安全环境中将操作限制为仅供分析
• ✅ 路径验证：全面验证项目和文件路径
• 🛡️ 错误处理：提供可靠的错误报告和可执行的建议

要求

系统要求

• Godot Engine：版本 3.5+ 或 4.0+（建议使用最新稳定版）
• Node.js 和 npm

AI 助手兼容性

• Cline 和 Roo Code：全面支持自动批准配置
• Cursor 和 VS Code：支持 UI 配置和项目专属配置
• Claude Desktop：兼容 MCP 服务集成
• 其他支持 MCP 的工具：任何支持 Model Context Protocol 的工具

安装

克隆并构建

# Clone the repository
git clone https://github.com/bradypp/godot-mcp.git
cd godot-mcp

# Install dependencies
npm install

# Build the project
npm run build

配置

选项 A：Cline 配置

添加到 Cline MCP 设置文件中：

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

选项 B：Cursor 配置

UI 配置

1. 打开 Cursor 设置 → 功能 → MCP
2. 点击 + 添加新的 MCP 服务
3. 配置：
   • 名称：godot
   • 类型：command
   • 命令：node /absolute/path/to/godot-mcp/build/index.js
4. 点击 添加，然后刷新服务列表

项目专属配置

在项目根目录中创建 .cursor/mcp.json：

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "DEBUG": "false",
        "GODOT_PATH": "/path/to/godot",
        "READ_ONLY_MODE": "false"
      }
    }
  }
}

环境变量

变量	描述	默认值	示例
GODOT_PATH	Godot 可执行文件的路径	自动检测	/usr/bin/godot4
DEBUG	启用详细日志	false	true
READ_ONLY_MODE	将操作限制为只读	false	true

API 参考

系统工具

get_godot_version

获取已安装的 Godot 版本信息。

参数：无

示例响应：

{
  "version": "4.2.1.stable",
  "platform": "linux.x86_64"
}

项目工具

launch_editor

启动指定项目的 Godot 编辑器。

参数：

• projectPath（字符串，必填）：Godot 项目目录的路径

示例：

{
  "projectPath": "/home/user/my-game"
}

run_project

运行 Godot 项目并捕获输出。

参数：

• projectPath（字符串，必填）：Godot 项目目录的路径
• scene（字符串，可选）：要运行的特定场景

示例：

{
  "projectPath": "/home/user/my-game",
  "scene": "scenes/MainMenu.tscn"
}

list_projects

在指定目录中查找 Godot 项目。

参数：

• directory（字符串，必填）：搜索项目的目录
• recursive（布尔值，可选）：是否递归搜索（默认值：false）

get_project_info

获取 Godot 项目的详细元数据。

参数：

• projectPath（字符串，必填）：Godot 项目目录的路径

示例响应：

{
  "name": "My Awesome Game",
  "path": "/home/user/my-awesome-game",
  "godotVersion": "4.2.1.stable.official",
  "structure": {
    "scenes": 12,
    "scripts": 8,
    "assets": 45,
    "other": 3
  }
}

场景管理工具

create_scene

在 Godot 项目中创建新场景。

参数：

• projectPath（字符串，必填）：Godot 项目目录的路径
• scenePath（字符串，必填）：新场景文件的路径（相对于项目）
• rootNodeType（字符串，可选）：根节点的类型（默认值："Node2D"）

示例：

{
  "projectPath": "/home/user/my-game",
  "scenePath": "scenes/Player.tscn",
  "rootNodeType": "CharacterBody2D"
}

add_node

向现有场景添加节点。

参数：

• projectPath（string，必填）：Godot 项目目录的路径
• scenePath（string，必填）：场景文件的路径（相对于项目）
• nodeType（string，必填）：要添加的节点类型（例如，"Sprite2D"、"CollisionShape2D"）
• nodeName（string，必填）：新节点的名称
• parentNodePath（string，可选）：父节点的路径（默认为根节点）
• properties（object，可选）：要设置的其他属性

示例：

{
  "projectPath": "/home/user/my-game",
  "scenePath": "scenes/Player.tscn",
  "nodeType": "Sprite2D",
  "nodeName": "PlayerSprite",
  "properties": {
    "position": { "x": 100, "y": 50 },
    "scale": { "x": 2.0, "y": 2.0 }
  }
}

edit_node

编辑场景中现有节点的属性。

参数：

• projectPath（string，必填）：Godot 项目目录的路径
• scenePath（string，必填）：场景文件的路径（相对于项目）
• nodePath（string，必填）：要编辑的节点的路径
• properties（object，必填）：要更新的属性

示例：

{
  "projectPath": "/home/user/my-game",
  "scenePath": "scenes/Player.tscn",
  "nodePath": "PlayerSprite",
  "properties": {
    "position": { "x": 200, "y": 100 },
    "modulate": { "r": 1.0, "g": 0.5, "b": 0.5, "a": 1.0 }
  }
}

remove_node

从场景中移除节点。

参数：

• projectPath（string，必填）：Godot 项目目录的路径
• scenePath（string，必填）：场景文件的路径（相对于项目）
• nodePath（string，必填）：要移除的节点的路径

load_sprite

将纹理载入 Sprite2D 节点。

参数：

• projectPath（string，必填）：Godot 项目目录的路径
• scenePath（string，必填）：场景文件的路径（相对于项目）
• nodePath（string，必填）：Sprite2D 节点的路径
• texturePath（string，必填）：纹理文件的路径（相对于项目）

save_scene

保存场景，也可将其保存为新的变体。

参数：

• projectPath（string，必填）：Godot 项目目录的路径
• scenePath（string，必填）：场景文件的路径（相对于项目）
• newPath（string，可选）：另存为变体的新路径

调试工具

get_debug_output

获取当前正在运行的项目的调试输出和错误。

参数：无

stop_project

停止当前正在运行的任何 Godot 项目。

参数：无

UID 工具（Godot 4.4+）

get_uid

获取 Godot 项目中特定文件的 UID。

参数：

• projectPath（string，必填）：Godot 项目目录的路径
• filePath（string，必填）：文件的路径（相对于项目）

update_project_uids

通过重新保存资源来更新项目中的 UID 引用。

参数：

• projectPath（string，必填）：Godot 项目目录的路径

项目架构

核心组件

Godot MCP 服务采用模块化架构，旨在提升可维护性和可扩展性：

src/
├── config/           # Configuration management
├── core/            # Core functionality
│   ├── GodotExecutor.ts      # Godot command execution
│   ├── PathManager.ts        # Path detection and validation
│   ├── ProcessManager.ts     # Process lifecycle management
│   └── ParameterNormalizer.ts # Input parameter handling
├── server/          # MCP server implementation
│   ├── GodotMCPServer.ts     # Main server class
│   └── types.ts              # Type definitions
├── tools/           # Tool implementations
│   ├── BaseToolHandler.ts    # Shared tool functionality
│   ├── ToolRegistry.ts       # Tool registration and filtering
│   ├── debug/               # Debug-related tools
│   ├── project/             # Project management tools
│   ├── scene/               # Scene manipulation tools
│   ├── system/              # System information tools
│   └── uid/                 # UID management tools
├── utils/           # Utility functions
└── scripts/         # Godot operation scripts

关键设计原则

1. 模块化工具系统：每个工具都独立封装，拥有自己的定义和处理器
2. 集中式配置：在一个位置管理环境变量和设置
3. 稳健的错误处理：提供全面的错误报告和可执行的建议
4. 安全优先：只读模式和输入验证可防止误用
5. 跨平台支持：采用与平台无关的设计，并在需要时进行特定于操作系统的处理

工具注册系统

工具在 ToolRegistry 中注册，并附带说明其功能的元数据：

export interface ToolRegistration {
  definition: ToolDefinition;
  handler: (args: any) => Promise<ToolResponse>;
  readOnly: boolean;
}

注册表会根据当前模式（只读或完全访问）自动筛选工具，并提供统一的工具发现和执行接口。

捆绑操作架构

复杂的 Godot 操作采用集中式 GDScript 方案：

1. 单个脚本文件：所有操作都整合在 godot_operations.gd 中
2. JSON 参数传递：操作接收结构化参数
3. 无需临时文件：避免文件系统开销和清理工作的复杂性
4. 一致的错误处理：所有操作采用标准化错误报告

与为每项操作生成临时脚本相比，这种架构能提供更好的性能、可维护性和可靠性。

使用示例

基本项目工作流

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

"Run my Godot project and show me any errors"

"Get information about my project structure and settings"

场景创建与管理

"Create a new Player scene with a CharacterBody2D root node"

"Add a Sprite2D node called 'PlayerSprite' to my Player scene"

"Load the character texture 'textures/player.png' into the PlayerSprite node"

"Set the Player's position to (100, 50) and scale to 2x"

"Create a CollisionShape2D node as a child of the Player root"

高级工作流

"Create a complete UI scene with buttons for Start Game, Settings, and Quit"

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

"Analyze my project structure and suggest performance improvements"

"Debug this GDScript error and help me fix the character controller"

"Create a save system scene with file I/O nodes and data management"

只读模式

只读模式提供了一种安全的方式，可在不进行任何修改的情况下分析 Godot 项目。这种模式非常适合 CI/CD 流水线、代码审查、教育环境和协作开发场景。

启用只读模式

将 READ_ONLY_MODE 环境变量设为 "true"：

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

可用与受限工具

✅ 只读模式下可用

系统工具：

• get_godot_version：获取 Godot 版本信息

项目工具：

• launch_editor：启动 Godot 编辑器
• run_project：运行项目以分析其行为
• list_projects：发现目录中的项目
• get_project_info：获取项目元数据

调试工具：

• get_debug_output：捕获控制台输出
• stop_project：停止正在运行的项目

UID 工具：

• get_uid：获取文件 UID（Godot 4.4+）

❌ 只读模式下受限

场景修改工具：

• create_scene：创建新场景
• add_node：向场景添加节点
• edit_node：修改节点属性
• remove_node：从场景中移除节点
• load_sprite：将纹理载入节点
• export_mesh_library：导出 MeshLibrary 资源
• save_scene：保存场景修改

UID 修改工具：

• update_project_uids：更新 UID 引用

使用场景

• 🔄 CI/CD 流水线：自动分析项目，无修改风险
• 👥 代码审查：安全检查项目，便于团队协作
• 📊 文档编写：提取项目信息以自动生成文档
• 🔍 调试：分析项目行为，无修改风险

故障排除

常见问题与解决方案

找不到 Godot

错误：Could not find a valid Godot executable path

解决方案：

1. 设置 GODOT_PATH 环境变量：

   export GODOT_PATH="/path/to/godot"
   # or for Windows:
   set GODOT_PATH="C:\Program Files\Godot\godot.exe"
   

2. 验证 Godot 安装：

   # Test if Godot is accessible
   godot --version
   # or try:
   godot4 --version
   

3. 常见的 Godot 路径：

   • Windows：C:\Program Files\Godot\godot.exe
   • macOS：/Applications/Godot.app/Contents/MacOS/Godot
   • Linux：/usr/bin/godot4 或 /usr/local/bin/godot

连接问题

错误：MCP 服务无响应或工具不可用

解决方案：

1. 配置更改后重启 AI 助手
2. 启用调试模式检查服务日志："DEBUG": "true"
3. 确认配置路径是绝对路径且正确
4. 手动测试服务：

   node /path/to/godot-mcp/build/index.js
   

项目路径无效

错误：Invalid project path 或 project.godot not found

解决方案：

1. 确保路径中包含 project.godot：

   ls /path/to/project/project.godot
   

2. 尽可能使用绝对路径
3. 检查项目目录的文件权限

构建问题

错误：构建失败或缺少依赖项

解决方案：

1. 清理并重新构建：

   npm run clean
   npm install
   npm run build
   

2. 清除 npm 缓存：

   npm cache clean --force
   

获取帮助

如果遇到此处未涵盖的问题：

1. 使用 DEBUG=true 检查调试日志
2. 在 GitHub 上搜索已有问题
3. 创建详细的问题报告，包含：
   • 操作系统及版本
   • Node.js 和 Godot 版本
   • 完整错误消息
   • 使用的配置
   • 重现步骤

常见问题

常见问题

问：支持哪些版本的 Godot？ 答：Godot 3.5+ 和所有 Godot 4.x 版本。部分功能（如 UID 管理）需要 Godot 4.4+。

问：可以将它用于 Godot 3.x 项目吗？ 答：可以，大多数功能都支持 Godot 3.5+。场景管理和项目操作均获得完整支持。

问：在生产项目中使用安全吗？ 答：安全，尤其是在启用只读模式的情况下。该服务包含全面的验证和错误处理。

技术问题

问：服务如何检测我的 Godot 安装？ 答：服务会检查各个平台的常见安装路径。你可以通过 GODOT_PATH 环境变量覆盖检测结果。

问：可以运行多个服务实例吗？ 答：可以，每个实例都独立运行。适合同时处理多个项目。

问：如果 Godot 在操作期间崩溃，会发生什么？ 答：服务会检测进程故障，并返回相应的错误消息和解决建议。

问：操作期间会创建临时文件吗？ 答：不会，服务采用打包的 GDScript 方案，无需创建临时文件，从而提升性能和安全性。

AI 助手集成

问：哪些 AI 助手可以与此服务配合使用？ 答：任何支持 Model Context Protocol 的 AI 助手都可以，包括 Cline、Roo Code、Cursor、VS Code、Claude Desktop 等。

问：可以自定义可用工具吗？ 答：可以，通过 autoApprove 配置进行自定义，也可以修改工具注册表来创建自定义构建。

问：如何确认集成正常工作？ 答：AI 助手应该能够列出可用工具并执行这些工具。启用调试模式即可查看详细的操作日志。

开发问题

问：可以向服务添加自定义工具吗？ 答：可以，模块化架构让添加新工具变得简单。开发指南请参见 CONTRIBUTING.md。

问：如何为项目作出贡献？ 答：Fork 此代码库，进行更改，然后提交拉取请求。请遵循现有代码风格并包含测试。

问：此服务可以扩展以支持其他游戏引擎吗？ 答：MCP 架构与引擎无关，但此实现是专为 Godot 设计的。也可以为其他引擎创建类似的服务。

贡献

欢迎为改进 Godot MCP 作出贡献！请参阅 CONTRIBUTING.md 指南，了解：

• 开发环境设置说明
• 代码风格指南
• 测试流程
• 拉取请求流程
• 问题报告指南

贡献者快速入门

# Fork and clone the repository
git clone https://github.com/your-username/godot-mcp.git
cd godot-mcp

# Install dependencies
npm install

# Start development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

许可证

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

致谢

本项目最初 Fork 自 Coding-Solo/godot-mcp。

支持

• 🐛 Bug 报告：GitHub Issues
• 💡 功能请求：GitHub Discussions
• 📖 文档：本文 README 和内联代码文档
• 💬 社区：加入有关 Godot MCP 和 AI 辅助开发的讨论

---

为 Godot 和 AI 开发社区倾心打造 ❤️