使用说明

Godot MCP

一个全面的模型上下文协议（MCP）服务器，用于将AI助手与Godot游戏引擎无缝集成。

什么是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服务器：

验证请求和项目结构
执行适当的Godot操作
返回详细的成功/错误反馈
使AI能够理解和响应结果

这创建了一个强大的反馈循环，AI助手可以从实际的Godot行为中学习，从而获得更准确的代码生成和调试帮助。

特性

核心项目管理

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

高级场景管理

🎬 创建新场景：生成具有指定根节点类型的场景
➕ 添加节点：将节点插入到具有可自定义属性的现有场景中
✏️ 编辑节点属性：修改位置、比例、纹理和其他节点属性
🗑️ 删除节点：通过删除不需要的节点来清理场景
🖼️ 负载喷洒：自动将纹理加载到Sprite2D节点中
🧱 导出网格库：将3D场景转换为GridMap的MeshLibrary资源
💾 保存场景变体：创建场景副本并管理场景版本

Godot 4.4+UID管理

🔗 获取文件UID：检索项目资源的唯一标识符
🔄 更新UID引用：在项目升级期间保持适当的资源链接

安全与安保

🔒 只读模式：将操作限制为仅对安全环境进行分析
✅ 路径验证：全面的项目和文件路径验证
🛡️ 错误处理：具有可操作建议的强大错误报告

需求

系统要求

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

AI助手兼容性

Cline&Roo代码：完全支持自动审批配置
光标和VS代码：支持UI和项目特定配置
克劳德桌面：与MCP服务器集成兼容
其他启用MCP的工具：支持模型上下文协议的任何工具

安装

克隆和构建

# 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 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：光标配置

UI配置

打开 光标设置 → 特性 → 主控程序
点击 +添加新的MCP服务器
配置：
- 名字: godot
- 类型: command
- 命令: node /absolute/path/to/godot-mcp/build/index.js
点击添加并刷新服务器列表

项目特定配置

创建 .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 （string，必填）：Godot项目目录的路径

示例:

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

`run_project`

执行Godot项目并捕获输出。

参数:

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

示例:

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

`list_projects`

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

参数:

directory （string，必填）：用于搜索项目的目录
recursive （布尔值，可选）：是否递归搜索（默认值：false）

`get_project_info`

检索有关Godot项目的详细元数据。

参数:

projectPath （string，必填）：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 （string，必填）：Godot项目目录的路径
scenePath （string，必填）：新场景文件的路径（相对于项目）
rootNodeType （字符串，可选）：根节点的类型（默认值：“Node2D”）

示例:

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

`add_node`

将节点添加到现有场景。

参数:

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

示例:

{
  "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 （字符串，必填）：要编辑的节点的路径
properties （对象，必填）：要更新的属性

示例:

{
  "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 （字符串，可选）：保存为变量的新路径

调试工具

`get_debug_output`

从正在运行的项目中检索当前调试输出和错误。

参数：无

`stop_project`

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

参数：无

UID工具（Godot 4.4+）

`get_uid`

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

参数:

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

`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

关键设计原则

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

工具注册系统

工具已在中注册 ToolRegistry 元数据指示它们的能力：

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

注册表根据当前模式（只读与完全访问）自动过滤工具，并为工具发现和执行提供统一的界面。

捆绑运营架构

复杂的Godot操作使用集中式GDScript方法：

单个脚本文件：所有业务合并为 godot_operations.gd
JSON参数传递：操作接收结构化参数
无临时文件：消除了文件系统开销和清理复杂性
一致的错误处理：所有业务的标准化错误报告

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

使用示例

基本项目工作流程

"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

解决方案:

设置GODOT_PATH环境变量:

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

验证Godot安装:

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

常见的Godot路径:
- 视窗: C:\Program Files\Godot\godot.exe
- macOS: /Applications/Godot.app/Contents/MacOS/Godot
- Linux: /usr/bin/godot4 或 /usr/local/bin/godot

连接问题

错误：MCP服务器没有响应或工具不可用

解决方案:

重启你的AI助手 配置更改后
检查服务器日志 通过启用调试模式： "DEBUG": "true"
验证配置路径 绝对正确
手动测试服务器:
```
node /path/to/godot-mcp/build/index.js
```

项目路径无效

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

解决方案:

确保路径包含project.godot:
```
ls /path/to/project/project.godot
```
使用绝对路径 在可能的情况下
检查文件权限 在项目目录上

构建问题

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

解决方案:

清理和重建:

npm run clean
npm install
npm run build

清除npm缓存:
```
npm cache clean --force
```

获取帮助

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

检查调试日志 随着 DEBUG=true
搜索现有问题 在GitHub上
创建详细的问题报告 与：
- 操作系统和版本
- Node.js和Godot版本
- 完整的错误消息
- 使用的配置
- 重现步骤

常见问题解答

一般问题

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

Q：我可以在Godot 3.x项目中使用它吗？ A：是的，大多数功能都适用于Godot 3.5+。场景管理和项目运营得到充分支持。

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

技术问题

Q：服务器如何检测我的Godot安装？ A：服务器检查每个平台的通用安装路径。您可以使用以下命令覆盖检测 GODOT_PATH 环境变量。

Q：我可以运行服务器的多个实例吗？ A：是的，每个实例都独立运行。适用于同时处理多个项目。

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

Q：操作过程中是否创建了临时文件？ A：不，服务器使用捆绑的GDScript方法，避免了临时文件创建，以获得更好的性能和安全性。

AI助手集成

Q：哪些AI助手与此服务器配合使用？ A：任何支持模型上下文协议的AI助手，包括Cline、Roo Code、Cursor、VS Code、Claude Desktop等。

Q：我可以自定义哪些工具可用吗？ A：是的，通过autoApprove配置或修改自定义生成的工具注册表。

Q：我如何知道集成是否有效？ A： AI助手应该能够列出可用的工具并执行它们。启用调试模式以查看详细的操作日志。

发展问题

Q：我可以向服务器添加自定义工具吗？ A：是的，模块化架构使添加新工具变得容易。看 CONTRIBUTING.md 发展指南。

Q：我如何为该项目做出贡献？ A：分叉存储库，进行更改，并提交拉取请求。请遵循现有的代码样式并包含测试。

Q：服务器是否可扩展到其他游戏引擎？ A： 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 文件以获取详细信息。

鸣谢

这个项目最初是从编程独奏/godot mcp.

支持

🐛 错误报告: GitHub问题
💡 功能请求: GitHub讨论
📖 文档：此README和内联代码文档
💬 社区：加入关于Godot MCP和人工智能辅助开发的讨论

内置于❤️ 面向Godot和AI开发社区

使用说明

Godot MCP

目录

什么是Godot MCP？

关键价值主张

运作原理

特性

核心项目管理

高级场景管理

Godot 4.4+UID管理

安全与安保

需求

系统要求

AI助手兼容性

安装

克隆和构建

配置

选项A：临床配置

选项B：光标配置

UI配置

项目特定配置

环境变量

api参考

系统工具

get_godot_version

项目工具

launch_editor

run_project

list_projects

get_project_info

场景管理工具

create_scene

add_node

edit_node

remove_node

load_sprite

save_scene

调试工具

get_debug_output

stop_project

UID工具（Godot 4.4+）

get_uid

update_project_uids

项目架构

核心组件

关键设计原则

工具注册系统

捆绑运营架构

使用示例

基本项目工作流程

场景创建与管理

高级工作流

只读模式

启用只读模式

可用工具与受限工具

✅ 在只读模式下可用

❌ 受限于只读模式

用例

故障排除

常见问题及解决方法

未找到Godot

连接问题

项目路径无效

构建问题

获取帮助

常见问题解答

一般问题

技术问题

AI助手集成

发展问题

贡献

贡献者快速入门

许可证

鸣谢

支持

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

`get_godot_version`

`launch_editor`

`run_project`

`list_projects`

`get_project_info`

`create_scene`

`add_node`

`edit_node`

`remove_node`

`load_sprite`

`save_scene`

`get_debug_output`

`stop_project`

`get_uid`

`update_project_uids`