戈多特MCP服务器
项目介绍
Godot MCP
一个全面的模型上下文协议（MCP）服务器，用于与Godot游戏引擎无缝集成AI助手。
目录
什么是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节点
- 🧱 导出MeshLibrary：将3D场景转换为GridMap使用的MeshLibrary资源
- 💾 保存场景变体：创建场景副本并管理场景版本
Godot 4.4+ UID管理
- 🔗 获取文件UID：检索项目资源的唯一标识符
- 🔄 更新UID引用：在项目升级期间维护正确的资源链接
安全性和安全性
- 🔒 只读模式：限制操作仅限于分析，适用于安全环境
- ✅ 路径验证：全面的项目和文件路径验证
- 🛡️ 错误处理：强大的错误报告，带有可操作的建议
系统需求
系统需求
- Godot引擎：版本3.5+或4.0+（推荐最新稳定版）
- Node.js & npm
AI助手兼容性
- Cline & Roo Code：完全支持，带有自动批准配置
- Cursor & VS Code：支持UI和项目特定配置
- Claude Desktop：与MCP服务器集成兼容
- 其他支持MCP的工具：任何支持模型上下文协议的工具
安装
克隆和构建
# 克隆仓库
git clone https://github.com/bradypp/godot-mcp.git
cd godot-mcp
# 安装依赖
npm install
# 构建项目
npm run build
配置
选项A：Cline配置
添加到你的Cline MCP设置文件中：
{
"mcpServers": {
"godot": {
"command": "node",
"args": ["/绝对路径/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配置
- 打开Cursor设置 → 功能 → MCP
- 点击**+ 新增MCP服务器**
- 配置：
- 名称：
godot - 类型：
命令 - 命令：
node /绝对路径/to/godot-mcp/build/index.js
- 名称：
- 点击添加并刷新服务器列表
项目特定配置
在项目根目录创建.cursor/mcp.json：
{
"mcpServers": {
"godot": {
"command": "node",
"args": ["/绝对路径/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": "我的精彩游戏",
"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(字符串，必需)：Godot项目的目录路径scenePath(字符串，必需)：场景文件的路径（相对于项目）nodeType(字符串，必需)：要添加的节点类型（例如："Sprite2D"，"CollisionShape2D"）nodeName(字符串，必需)：新节点的名称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(字符串，必需)：Godot项目的目录路径scenePath(字符串，必需)：场景文件的路径（相对于项目）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(字符串，必需)：Godot项目的目录路径scenePath(字符串，必需)：场景文件的路径（相对于项目）nodePath(字符串，必需)：要移除的节点路径
load_sprite
将纹理加载到Sprite2D节点。
参数：
projectPath(字符串，必需)：Godot项目的目录路径scenePath(字符串，必需)：场景文件的路径（相对于项目）nodePath(字符串，必需)：Sprite2D节点的路径texturePath(字符串，必需)：纹理文件的路径（相对于项目）
save_scene
保存场景，可选地作为新的变体。
参数：
projectPath(字符串，必需)：Godot项目的目录路径scenePath(字符串，必需)：场景文件的路径（相对于项目）newPath(字符串，可选)：作为变体保存的新路径
调试工具
get_debug_output
检索正在运行项目的当前调试输出和错误。
参数：无
stop_project
停止任何正在运行的Godot项目。
参数：无
UID工具（Godot 4.4+）
get_uid
获取Godot项目中特定文件的UID。
参数：
projectPath(字符串，必需)：Godot项目的目录路径filePath(字符串，必需)：文件的路径（相对于项目）
update_project_uids
通过重新保存资源来更新项目中的UID引用。
参数：
projectPath(字符串，必需)：Godot项目的目录路径
项目架构
核心组件
Godot MCP服务器遵循一种模块化的架构设计，旨在提高可维护性和扩展性：
src/
├── config/ # 配置管理
├── core/ # 核心功能
│ ├── GodotExecutor.ts # Godot命令执行
│ ├── PathManager.ts # 路径检测和验证
│ ├── ProcessManager.ts # 进程生命周期管理
│ └── ParameterNormalizer.ts # 输入参数处理
├── server/ # MCP服务器实现
│ ├── GodotMCPServer.ts # 主服务器类
│ └── types.ts # 类型定义
├── tools/ # 工具实现
│ ├── BaseToolHandler.ts # 共享工具功能
│ ├── ToolRegistry.ts # 工具注册和过滤
│ ├── debug/ # 调试相关工具
│ ├── project/ # 项目管理工具
│ ├── scene/ # 场景操作工具
│ ├── system/ # 系统信息工具
│ └── uid/ # UID管理工具
├── utils/ # 实用函数
└── scripts/ # Godot操作脚本
关键设计原则
- 模块化工具系统：每个工具都是独立的，有自己的定义和处理器
- 集中式配置：环境变量和设置在一个位置管理
- 强大的错误处理：全面的错误报告，带有可操作的建议
- 安全第一：只读模式和输入验证防止误用
- 跨平台支持：平台无关的设计，在需要时处理操作系统特定的情况
工具注册系统
工具在ToolRegistry中注册，带有指示其能力的元数据：
export interface ToolRegistration {
definition: ToolDefinition;
handler: (args: any) => Promise<ToolResponse>;
readOnly: boolean;
}
注册表根据当前模式（只读或全访问）自动过滤工具，并提供统一的工具发现和执行接口。
捆绑操作架构
复杂的Godot操作采用集中的GDScript方法：
- 单个脚本文件：所有操作集中在
godot_operations.gd - JSON参数传递：操作接收结构化的参数
- 无临时文件：消除文件系统开销和清理复杂性
- 一致的错误处理：所有操作中标准化的错误报告
这种架构提供了比为每个操作生成临时脚本更好的性能、可维护性和可靠性。
使用示例
基本项目流程
"为我在/path/to/my-game启动Godot编辑器"
"运行我的Godot项目并显示任何错误"
"获取有关我的项目结构和设置的信息"
场景创建和管理
"创建一个带有CharacterBody2D根节点的新玩家场景"
"在我的玩家场景中添加一个名为'PlayerSprite'的Sprite2D节点"
"将角色纹理'textures/player.png'加载到PlayerSprite节点"
"将玩家的位置设置为(100, 50)，比例设置为2x"
"在玩家根节点下创建一个CollisionShape2D子节点"
高级工作流程
"创建一个带有开始游戏、设置和退出按钮的完整UI场景"
"导出我的3D级别模型作为GridMap使用的MeshLibrary"
"分析我的项目结构并提出性能改进"
"调试这个GDScript错误并帮助我修复角色控制器"
"创建一个带有文件I/O节点和数据管理的保存系统场景"
只读模式
只读模式提供了一种安全的方式来分析Godot项目而不进行任何修改。这对于CI