Godot MCP
((((((( (((((((
((((((((((( (((((((((((
((((((((((((( (((((((((((((
(((((((((((((((((((((((((((((((((
(((((((((((((((((((((((((((((((((
((((( ((((((((((((((((((((((((((((((((((((((((( (((((
(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
(((((((((((@@@@@@@(((((((((((((((((((((((((((@@@@@@@(((((((((((
(((((((((@@@@,,,,,@@@(((((((((((((((((((((@@@,,,,,@@@@(((((((((
((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((
((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((
(((((((((@@@,,,,,,,@@((((((((@@@@@((((((((@@,,,,,,,@@@(((((((((
((((((((((((@@@@@@(((((((((((@@@@@(((((((((((@@@@@@((((((((((((
(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
@@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@
((((((((( @@@(((((((((((@@(((((((((((@@(((((((((((@@@ (((((((((
(((((((((( @@((((((((((@@@(((((((((((@@@((((((((((@@ ((((((((((
(((((((((((@@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@(((((((((((
(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
(((((((((((((((((((((((((((((((((((((((((((((((((((((
(((((((((((((((((((((((((((((((((((((((((((((((
(((((((((((((((((((((((((((((((((
/$$ /$$ /$$$$$$ /$$$$$$$
| $$$ /$$$ /$$__ $$| $$__ $$
| $$$$ /$$$$| $$ \__/| $$ \ $$
| $$ $$/$$ $$| $$ | $$$$$$$/
| $$ $$$| $$| $$ | $$____/
| $$\ $ | $$| $$ $$| $$
| $$ \/ | $$| $$$$$$/| $$
|__/ |__/ \______/ |__/
用于与 Godot 游戏引擎交互的模型上下文协议 (MCP) 服务器。
介绍
Godot MCP 使 AI 助手能够启动 Godot 编辑器、运行项目、捕获调试输出并控制项目执行——所有这些都通过标准化界面完成。
这种直接反馈循环可以帮助 Claude 这样的 AI 助手了解在真实的 Godot 项目中什么有效、什么无效，从而提供更好的代码生成和调试帮助。
特征
- 启动 Godot 编辑器：打开特定项目的 Godot 编辑器
- 运行 Godot 项目：在调试模式下执行 Godot 项目
- 捕获调试输出：检索控制台输出和错误消息
- 控制执行：以编程方式启动和停止 Godot 项目
- 获取 Godot 版本：检索已安装的 Godot 版本
- 列出 Godot 项目：在指定目录中查找 Godot 项目
- 项目分析：获取有关项目结构的详细信息
- 场景管理：
- 创建具有指定根节点类型的新场景
- 将节点添加到具有可自定义属性的现有场景
- 将精灵和纹理加载到 Sprite2D 节点中
- 将 3D 场景导出为 GridMap 的 MeshLibrary 资源
- 使用创建变体的选项保存场景
- UID 管理（适用于 Godot 4.4+）：
- 获取特定文件的 UID
- 通过重新保存资源来更新 UID 引用
要求
安装和配置
步骤 1：安装和构建
首先，克隆存储库并构建 MCP 服务器：
git clone https://github.com/Coding-Solo/godot-mcp.git
cd godot-mcp
npm install
npm run build
第 2 步：使用您的 AI 助手进行配置
选项 A：使用 Cline 配置
添加到您的 Cline MCP 设置文件（ ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ）：
{
"mcpServers": {
"godot": {
"command": "node",
"args": ["/absolute/path/to/godot-mcp/build/index.js"],
"env": {
"DEBUG": "true" // Optional: Enable detailed logging
},
"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"
]
}
}
}
选项 B：使用光标配置
使用光标 UI：
- 前往**“光标设置”** > “功能” > “MCP”
- 点击**+ 添加新的 MCP 服务器**按钮
- 填写表格：
- 名称：
godot （或您喜欢的任何名称） - 类型：
command - 命令：
node /absolute/path/to/godot-mcp/build/index.js
- 点击“添加”
- 您可能需要按 MCP 服务器卡右上角的刷新按钮来填充工具列表
使用项目特定配置：
在项目目录中创建一个文件.cursor/mcp.json ，内容如下：
{
"mcpServers": {
"godot": {
"command": "node",
"args": ["/absolute/path/to/godot-mcp/build/index.js"],
"env": {
"DEBUG": "true" // Enable detailed logging
}
}
}
}
步骤3：可选环境变量
您可以使用以下环境变量自定义服务器行为：
GODOT_PATH ：Godot 可执行文件的路径（覆盖自动检测）DEBUG ：设置为“true”以启用详细的服务器端调试日志记录
示例提示
配置完成后，你的 AI 助手将在需要时自动运行 MCP 服务器。你可以使用以下提示：
"Launch the Godot editor for my project at /path/to/project"
"Run my Godot project and show me any errors"
"Get information about my Godot project structure"
"Analyze my Godot project structure and suggest improvements"
"Help me debug this error in my Godot project: [paste error]"
"Write a GDScript for a character controller with double jump and wall sliding"
"Create a new scene with a Player node in my Godot project"
"Add a Sprite2D node to my player scene and load the character texture"
"Export my 3D models as a MeshLibrary for use with GridMap"
"Create a UI scene with buttons and labels for my game's main menu"
"Get the UID for a specific script file in my Godot 4.4 project"
"Update UID references in my Godot project after upgrading to 4.4"
实现细节
建筑学
Godot MCP 服务器使用捆绑的 GDScript 方法执行复杂操作：
- 直接命令：启动编辑器或获取项目信息等简单操作直接使用 Godot 的内置 CLI 命令。
- 捆绑操作脚本：创建场景或添加节点等复杂操作使用单个、全面的 GDScript 文件（
godot_operations.gd ）来处理所有操作。
这种架构有以下几个好处：
- 无临时文件：无需临时脚本文件，保持系统清洁
- 简化的代码库：将所有 Godot 操作集中在一个（某种程度上）有组织的文件中
- 更好的可维护性：更容易添加新操作或修改现有操作
- 改进的错误处理：为所有操作提供一致的错误报告
- 减少开销：最小化文件 I/O 操作以获得更好的性能
捆绑脚本接受操作类型和参数作为 JSON，允许灵活、动态地执行操作，而无需为每个操作生成临时文件。
故障排除
- Godot Not Found ：将 GODOT_PATH 环境变量设置为你的 Godot 可执行文件
- 连接问题：确保服务器正在运行并重新启动你的AI助手
- 无效的项目路径：确保路径指向包含 project.godot 文件的目录
- 构建问题：确保通过运行
npm install安装了所有依赖项 - 对于光标具体来说：
- 确保 MCP 服务器显示并在 Cursor 设置（设置 > MCP）中启用
- MCP 工具只能使用 Agent 聊天配置文件（Cursor Pro 或 Business 订阅）运行
- 使用“Yolo 模式”自动运行 MCP 工具请求
执照
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。