戈多特-MCP服务器

Name: 戈多特-MCP服务器
Author: Derfirm

作者：Derfirm7 星标更新：2025-10-13

安装使用来源：spider==github.com

项目介绍

Godot MCP

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

简介

Godot MCP使AI助手能够启动Godot编辑器，运行项目，捕获调试输出，并通过标准化接口控制项目执行。

这种直接反馈循环有助于AI助手理解在Godot项目中哪些有效，哪些无效，从而生成更好的代码并提供调试帮助。

当前版本： 0.1.0
所需Godot版本： 4.5.0或更高版本
状态： 活跃开发

功能

启动Godot编辑器：为特定项目打开Godot编辑器
运行Godot项目：以调试模式执行Godot项目
捕获调试输出：获取控制台输出和错误消息
控制执行：通过编程方式启动和停止Godot项目
获取Godot版本：检索已安装的Godot版本
列出Godot项目：查找指定目录中的Godot项目
项目分析：获取关于项目结构的详细信息

场景管理

使用指定根节点类型创建新场景
添加、删除、修改和复制节点
查询节点信息和属性
将精灵和纹理加载到Sprite2D节点中
将3D场景导出为GridMap使用的MeshLibrary资源
带有创建变体选项保存场景

脚本管理

使用模板（节点、资源、自定义）创建GDScript文件
将脚本附加到节点
通过详细的错误报告验证脚本语法
获取节点方法和属性

资源管理

使用自定义设置导入资产
创建资源（材质、着色器等）
列出带有元数据的项目资产
配置导入设置

信号系统

在脚本中创建自定义信号
在节点之间连接信号并进行验证
列出节点上的可用信号
断开信号连接

物理系统（Godot 4.5+）

添加物理体（CharacterBody2D/3D、RigidBody2D/3D等）
配置物理属性和材质
设置碰撞层和掩码
创建带有信号连接的Area2D/Area3D

用户界面系统

创建UI元素（按钮、标签、文本编辑框、面板等）
应用主题到UI元素
设置容器布局
创建带有按钮和导航的菜单

动画系统

创建带有动画的AnimationPlayer节点
向动画轨道添加关键帧
设置带有状态机的AnimationTree
添加粒子系统（GPUParticles2D/3D）

项目管理

更新项目设置
配置输入动作映射
设置自动加载单例
管理编辑器插件（列出、启用、禁用）

调试模块

以全调试输出捕获运行项目
获取带有堆栈跟踪的错误上下文
智能错误分析并提供解决方案
与文档集成以提供上下文帮助

文档模块（Godot 4.5+）

从官方Godot文档获取详细的类信息
搜索文档中的类、方法、属性和信号
获取带有参数和示例的方法信息
访问关于常见Godot主题的最佳实践（物理、信号、GDScript等）
自动缓存以提高性能
支持Godot 4.5+特性并警告废弃特性

UID管理（Godot 4.4+）

获取特定文件的UID
通过重新保存资源更新UID引用

要求

Godot Engine 4.5.0或更高版本 安装在您的系统上
- 服务器在启动时会验证您的Godot版本
- 最低版本：4.5.0
- 推荐：最新稳定版（4.5.x）
Node.js 18+ 和 npm
支持MCP的AI助手（Cline、Cursor等）

版本兼容性

此MCP服务器需要Godot 4.5.0或更高版本以确保与现代Godot特性的兼容性：

UID系统：资源的唯一标识符（4.4+，在4.5+中稳定）
合成器效果：高级渲染管线（4.5+）
增强物理：具有吸收属性的改进物理材料系统（4.5+）
改进的GDScript：具有详细错误报告的更好解析器（4.5+）
现代节点类型：最新的节点类型和API（4.5+）
GPUParticles：增强的粒子系统（4.5+）

服务器在启动时会自动验证您的Godot版本，并在版本不兼容时提供明确的错误消息。

安装和配置

第一步：安装和构建

克隆仓库并构建MCP服务器：

git clone https://github.com/Derfirm/godot-mcp.git
cd godot-mcp
npm install
npm run build

构建过程编译TypeScript并捆绑GDScript操作文件。

第二步：与您的AI助手配置

选项A：使用Cline配置

在您的Cline MCP设置文件中添加以下内容：

Mac/Linux：~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows：%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/绝对路径/to/godot-mcp/build/index.js"],
      "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",
        "remove_node",
        "modify_node",
        "duplicate_node",
        "query_node",
        "load_sprite",
        "export_mesh_library",
        "save_scene",
        "create_script",
        "attach_script",
        "validate_script",
        "get_node_methods",
        "import_asset",
        "create_resource",
        "list_assets",
        "configure_import",
        "create_signal",
        "connect_signal",
        "list_signals",
        "disconnect_signal",
        "add_physics_body",
        "configure_physics",
        "setup_collision_layers",
        "create_area",
        "create_ui_element",
        "apply_theme",
        "setup_layout",
        "create_menu",
        "create_animation_player",
        "add_keyframes",
        "setup_animation_tree",
        "add_particles",
        "get_uid",
        "update_project_uids",
        "get_class_info",
        "get_method_info",
        "search_docs",
        "get_best_practices",
        "run_with_debug",
        "get_error_context",
        "run_scene",
        "capture_screenshot",
        "list_missing_assets",
        "remote_tree_dump",
        "toggle_debug_draw",
        "update_project_settings",
        "configure_input_map",
        "setup_autoload",
        "manage_plugins"
      ]
    }
  }
}

选项B：使用Cursor配置

使用Cursor UI：

转到Cursor设置 > 功能 > MCP
单击**+ 添加新MCP服务器**按钮
填写表单：
- 名称：godot（或您喜欢的任何名称）
- 类型：command
- 命令：node /绝对路径/to/godot-mcp/build/index.js
单击“添加”
您可能需要点击MCP服务器卡片右上角的刷新按钮来填充工具列表

使用项目特定配置：

在项目目录中创建一个.cursor/mcp.json文件，内容如下：

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/绝对路径/to/godot-mcp/build/index.js"],
      "env": {
        "DEBUG": "true"                  // 启用详细日志
      }
    }
  }
}

第三步：可选环境变量

您可以使用环境变量自定义服务器行为：

GODOT_PATH：Godot可执行文件的路径（覆盖自动检测）
DEBUG：设置为"true"以启用详细的服务器端日志

示例：

export GODOT_PATH="/路径/to/godot"
export DEBUG="true"

检查您的Godot版本

您可以验证您的Godot安装并检查支持的功能，使用get_godot_version工具：

"我安装了哪个版本的Godot？"
"检查我的Godot版本是否支持所有功能"

该工具将显示：

您已安装的Godot版本
与MCP服务器的兼容性状态
根据您的版本支持的功能列表

您也可以手动检查：

godot --version
# 或
/path/to/Godot.app/Contents/MacOS/Godot --version

示例提示

配置完成后，您的AI助手将在需要时自动运行MCP服务器。您可以使用以下提示：

基本操作

"为我在/path/to/project的项目启动Godot编辑器"
"运行我的Godot项目并显示任何错误"
"获取有关我的Godot项目结构的信息"
"我安装了哪个版本的Godot？"

场景及节点管理

"创建一个新的2D场景，根节点为CharacterBody2D"
"在我的玩家场景中添加一个Sprite2D节点并加载角色纹理"
"从我的级别场景中删除旧的敌人节点"
"修改玩家节点，将其位置设置为(100, 200)"
"复制敌人的节点并放置在不同的位置"

脚本管理

"为玩家控制器创建一个新的GDScript"
"将玩家脚本附加到CharacterBody2D节点"
"验证我的player.gd脚本是否有语法错误"
"显示CharacterBody2D节点上可用的所有方法"

物理与碰撞

"在我的场景中添加一个带有胶囊碰撞形状的CharacterBody2D"
"为玩家、敌人和环境设置碰撞层"
"创建一个用于检测玩家进入区域的Area2D"
"配置我的RigidBody2D的物理属性"

UI与菜单

"创建一个主菜单UI，带有开始、选项和退出按钮"
"添加一个标签以显示玩家得分"
"为我的设置菜单设置VBoxContainer布局"
"应用自定义主题到我的UI元素"

动画与粒子

"为我的角色创建一个带有空闲和行走动画的AnimationPlayer"
"向动画轨道添加关键帧以动画化玩家的位置"
"设置带有状态机的AnimationTree以处理角色状态"
"为玩家跳跃添加粒子效果"

项目配置

"更新我的项目设置，将窗口大小设置为1920x1080"
"配置输入动作移动左、移动右和跳跃"
"设置GameManager作为自动加载单例"
"列出所有已安装的编辑器插件"

调试与文档

"以调试模式运行我的项目并捕获所有输出"
"帮我理解这个错误：[粘贴错误消息]"
"显示CharacterBody2D类的文档"
"搜索Godot文档中的move_and_slide"
"在Godot中使用信号的最佳实践是什么？"

高级操作

"将我的3D模型导出为GridMap使用的MeshLibrary"
"获取我在Godot 4.4项目中的特定脚本文件的UID"
"将按钮的pressed信号连接到start_game方法"
"使用特定压缩设置导入纹理"

实现细节

架构

Godot MCP服务器使用捆绑的GDScript方法进行高效的操作执行：

1. TypeScript服务器层

处理MCP协议通信
管理Godot进程生命周期
验证参数和版本
缓存文档和结果

2. 捆绑的GDScript操作

单个综合脚本（godot_operations.gd）用于所有操作
接受操作类型和参数作为JSON
在无头模式下运行以快速执行
返回结构化的JSON结果

3. 文档模块

使用Godot的--doctool获取类信息
本地缓存文档以提高性能
提供搜索和最佳实践

关键优势

无需临时文件：所有操作都使用单一捆绑脚本
快速执行：无头模式，最小开销
类型安全：参数验证和规范化
版本感知：基于Godot版本自动检测功能
全面缓存：文档和结果缓存以提高速度

支持的操作

服务器支持跨多个类别的50多种操作：

场景管理（创建、修改、查询节点）
脚本管理（创建、附加、验证脚本）
资源管理（导入、配置资产）
物理系统（身体、碰撞、材质）
UI系统（元素、主题、布局）
动画系统（播放器、关键帧、树）
信号系统（创建、连接、断开）
调试工具（运行、捕获、分析）
文档（搜索、类信息、最佳实践）
项目管理（设置、输入、自动加载）

故障排除

常见问题

未找到Godot

设置GODOT_PATH环境变量指向您的Godot可执行文件
验证Godot是否在您的系统PATH中
检查路径是否指向正确的Godot 4.5+可执行文件

版本不兼容

从godotengine.org升级到Godot 4.5.0或更高版本
运行godot --version以验证您的安装
使用get_godot_version工具检查兼容性

连接问题

在更改配置后重启您的AI助手
检查配置中的MCP服务器路径是否正确
启用DEBUG模式以查看详细日志

无效项目路径

确保路径指向包含project.godot文件的目录
使用绝对路径以提高可靠性
检查文件权限

构建问题

运行npm install以确保所有依赖项均已安装
删除node_modules和build文件夹，然后重新构建
确保您已安装Node.js 1.8+

对于Cursor用户

确保在设置 > 功能 > MCP中启用了MCP服务器
只能使用代理聊天配置文件（Cursor Pro或Business订阅）运行MCP工具
使用“Yolo模式”进行自动工具执行
在更改配置后重启Cursor
在Cursor的开发者工具中检查MCP服务器日志

对于Cline用户

验证Cline的MCP设置中的服务器路径
检查服务器是否正在运行（查看启动消息）
对于经常使用的工具启用自动批准

贡献

欢迎贡献！请参阅CONTRIBUTING.md了解指南。

发展路线图

音频系统操作（AudioStreamPlayer、总线、3D音频）
3D场景操作（材质、环境、合成器）
性能分析工具
影片捕捉功能
扩展的调试可视化模式
扩展的文档集成

详见.kiro/specs/godot-game-assistant/tasks.md以获取详细的实施计划。

文档生成

服务器自动使用--doctool标志生成并缓存Godot文档。这在您使用与文档相关的工具时透明地发生。

手动文档生成

如果您想预生成文档或清除缓存：

# 创建缓存目录
mkdir -p .godot-docs-cache/doctool

# 为所有Godot类生成文档
godot --doctool .godot-docs-cache/doctool --no-docbase --headless --quit

# 或使用自定义Godot路径（macOS示例）
/Applications/Godot.app/Contents/MacOS/Godot --doctool .godot-docs-cache/doctool --no-docbase --headless --quit

# Windows示例
"C:\Program Files\Godot\Godot.exe" --doctool .godot-docs-cache/doctool --no-docbase --headless --quit

# Linux示例
/usr/bin/godot --doctool .godot-docs-cache/doctool --no-docbase --headless --quit

注意：

--headless和--quit标志确保Godot在没有GUI的情况下运行并在生成文档后退出
--no-docbase标志生成类结构（方法、属性、信号），而不包括详细的描述
MCP服务器提供在线文档链接以获取完整详情

文档缓存

默认位置：~/.godot-docs-cache/（用户的家目录）
自定义位置：设置MCP_CACHE_DIR环境变量以指定不同的目录
内容：
- doctool/ - Godot生成的原始XML文档
- *.json - 解析和缓存的类信息
大小：通常根据使用情况在10-50MB之间
清除：删除.godot-docs-cache/目录以重新生成

环境变量示例：

# 设置自定义缓存目录
export MCP_CACHE_DIR=/路径/to/your/cache