内容
# Godot MCP
[](LICENSE)
[](.)
[](https://www.npmjs.com/package/@yanhuifair/godot-mcp)
[中文文档](README-zh.md)
> **Godot 引擎模型上下文协议服务器** — 281 种工具，26 个类别，支持 Godot 4.6/4.7。基于文件的增删改查 + 实时编辑器插件。AI 助手通过 **标准输入输出**、**SSE** 或 **可流式 HTTP** 传输读取、检查和修改 Godot 项目。
---
## 目录
- [快速入门](#快速入门)
- [功能概述](#功能概述)
- [所有工具](#所有工具)
- [安装](#安装)
- [AI 客户端配置](#ai-客户端配置)
- [使用示例](#使用示例)
- [编辑器插件](#编辑器插件)
- [架构](#架构)
- [支持的格式](#支持的格式)
- [开发](#开发)
- [构建 VSIX](#构建-vsix)
---
## 快速入门
### 1. 安装插件（一次性）
```bash
npx @yanhuifair/godot-mcp --install-addons -p /path/to/your/godot/project
```
然后在 Godot 中启用：**项目 → 项目设置 → 插件 → Godot MCP → 启用**。
### 2. 配置 AI 客户端
在项目根目录中创建 `.vscode/mcp.json`（或参见 [AI 客户端配置](#ai-客户端配置) 以获取其他客户端的配置）：
```json
{
"mcpServers": {
"godot-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@yanhuifair/godot-mcp", "-p", "."]
}
}
}
```
### 3. 开始聊天
AI 客户端会自动启动 MCP 服务器。**基于文件的工具**（.tscn, .tres, .gd）立即生效。**编辑器工具**（播放、选择节点等）会使 MCP 自动启动 Godot - 无需手动打开编辑器。
> "列出项目中的所有场景"
> "查找所有 CharacterBody2D 节点"
> "运行游戏并截图"
---
## 功能概述
| 类别 | 工具 | 亮点 |
|---|---|---|
| **编辑器** | 78 | 实时编辑器控制：选择、播放、撤销、保存、断点、搜索、文件操作、性能 |
| **场景** | 21 | 完整的场景增删改查 + 节点添加/删除/修改/克隆 + 信号 + 变换 + 碰撞 + 精灵 |
| **项目** | 22 | 配置读取/写入、输入映射、文件操作、自动加载、验证、未使用资产检测 |
| **脚本** | 21 | GDScript/Shader 增删改查 + 结构分析 + 代码搜索 + 信号/函数/导出注入 + 着色器验证/编译 |
| **领域** | 11 | 曲线、梯度、路径、骨骼、反射探头、多网格、噪声纹理 |
| **动画** | 10 | AnimationPlayer/AnimationTree 完整流程：创建、轨道、关键帧、参数 |
| **Godot 引擎** | 9 | 引擎检测、启动编辑器、运行/导出项目、截图、进程控制 |
| **覆盖** | 8 | 网格原语、2D 灯光、车辆身体、弹簧臂、贴花、遮挡器 |
| **节点** | 8 | CharacterBody、AnimatedSprite、音频、视频、视差、富文本、容器、选项卡 |
| **资源** | 8 | .tres 增删改查、PBR 材料、主题、14 个模板 |
| **音频** | 7 | 音频总线布局增删改查、效果、音量、音频文件检测 |
| **着色器图** | 7 | VisualShader 图节点添加/删除/连接、参数编辑 |
| **实用工具** | 6 | 所有信号列表、StyleBox、AtlasTexture、弹出窗口、项目图标、凝聚力报告 |
| **渲染** | 5 | MeshInstance、Viewport、区域、RayCast/ShapeCast |
| **环境** | 4 | 环境 .tres 读取/写入 + 4 个预设 |
| **检查器** | 5 | 相机、灯光、粒子节点检查和编辑 |
| **物理** | 4 | 物理材料增删改查、碰撞层名称 |
| **导入** | 3 | .import 文件读取/写入和列表 |
| **TileMap** | 3 | TileSet 资源解析、TileMapLayer 检查 |
| **导航** | 3 | NavigationRegion 检查 + NavigationMesh 创建 |
| **翻译** | 3 | CSV/PO 翻译文件读取/写入 |
| **关节** | 3 | 物理关节创建、参数、列表 |
| **UID** | 3 | 文件 UID 查询、批量更新、缺失 UID 检测 |
| **2D 几何** | 2 | CollisionPolygon2D、CollisionShape2D 形状配置 |
| **差异** | 2 | 场景和资源逐行/属性比较 |
| **其他** | 8 | GDExtension、C#、World3D、CameraAttributes、SpriteFrames、GridMap、纹理 |
**总计：26 个类别中的 281 种工具**
## 所有工具
> 🔍 点击每个类别以展开并查看所有工具的描述。有关详细用法示例，请参阅 [用法示例](#usage-examples)。编辑器工具也在 [编辑器插件](#editor-plugin) 中列出并附有描述。
<details>
<summary><b>🎬 编辑器</b> (89 个工具) — 编辑器实时控制</summary>
| 工具 | 描述 |
|---|---|
| `editor_get_selection` | 获取编辑器中选定的节点。 |
| `editor_set_selection` | 在编辑器中选择节点。 |
| `editor_get_open_scene` | 获取当前打开的场景路径。 |
| `editor_read_current_scene` | 读取编辑器实时场景树。 |
| `editor_get_info` | 获取编辑器状态信息。 |
| `editor_get_rect` | 获取编辑器窗口尺寸。 |
| `editor_focus` | 将 Godot 编辑器窗口带到前台。 |
| `editor_show_in_filesystem` | 在文件系统停靠中显示文件。 |
| `editor_open_dock` | 打开停靠：文件系统、检查器、场景、输出。 |
| `editor_play` | 从编辑器运行项目。 |
| `editor_stop` | 在编辑器中停止运行。 |
| `editor_run_specific_scene` | 运行特定场景（而不仅仅是主场景）。 |
| `editor_get_running_scene_tree` | 获取游戏运行时实时的场景树。 |
| `editor_get_performance_monitors` | 获取游戏运行时帧率、绘制调用、内存使用情况。 |
| `editor_undo` | 撤销上一次编辑器操作。 |
| `editor_redo` | 重做上一次撤销的操作。 |
| `editor_save` | 保存编辑器中的当前场景。 |
| `editor_save_all` | 保存所有打开的场景。 |
| `editor_reload_scene` | 保存并重新加载当前场景。 |
| `editor_delete_selected` | 删除当前选定的节点。 |
| `editor_create_scene` | 在编辑器中创建并打开新场景。 |
| `editor_instantiate_scene` | 将 PackedScene 实例化到当前场景中。 |
| `editor_set_main_scene` | 设置项目的主场景。 |
| `editor_get_scene_changes` | 检查当前场景是否有未保存的更改。 |
| `editor_add_node` | 在编辑器中向当前打开的场景添加节点。 |
| `editor_remove_node` | 从当前打开的场景中删除节点。 |
| `editor_duplicate_node` | 复制具有子节点、脚本和信号的节点。 |
| `editor_rename_node` | 在编辑器中重命名节点。 |
| `editor_reparent_node` | 将节点移动到新父节点。 |
| `editor_move_node` | 将 2D/3D 节点移动到新位置。 |
| `editor_get_node_properties` | 读取节点的编辑器可见属性。 |
| `editor_set_node_properties` | 一次性设置节点的多个属性。 |
| `editor_create_script` | 在编辑器中创建并打开新 GDScript。 |
| `editor_attach_script` | 将脚本附加到编辑器中的节点。 |
| `editor_run_gdscript` | 在编辑器上下文中执行任意 GDScript 代码。 |
| `editor_evaluate_expression` | 在调试器/编辑器上下文中评估 GDScript 表达式。 |
| `editor_set_breakpoint` | 在脚本中设置断点。 |
| `editor_remove_breakpoint` | 从脚本中删除断点。 |
| `editor_get_breakpoints` | 列出所有断点。 |
| `editor_debug_continue` | 在调试器中恢复执行。 |
| `editor_debug_step` | 进入调试器中的下一行。 |
| `editor_debug_step_over` | 在调试器中跳过当前行。 |
| `editor_debug_break` | 在调试器中停止执行（中断）。 |
| `editor_get_stack_trace` | 从调试器获取当前调用堆栈。 |
| `editor_get_debug_variables` | 从调试器获取局部变量。 |
| `editor_connect_signal` | 在编辑器中连接节点之间的信号。 |
| `editor_disconnect_signal` | 断开节点之间的信号。 |
| `editor_list_node_signals` | 列出节点上的信号及其连接。 |
| `editor_open_asset` | 在编辑器中打开资产。 |
| `editor_list_filesystem` | 列出编辑器文件系统中的文件和目录。 |
| `editor_create_folder` | 通过编辑器文件系统在项目中创建目录。 |
| `editor_delete_asset` | 通过编辑器删除文件或文件夹。 |
| `editor_rename_asset` | 通过编辑器文件系统重命名文件。 |
| `editor_move_asset` | 通过编辑器将文件移动到新位置。 |
| `editor_duplicate_asset` | 通过编辑器文件系统复制文件。 |
| `editor_reimport_asset` | 强制重新导入资产。 |
| `editor_get_dependency_list` | 获取文件的资源依赖项列表。 |
| `editor_get_project_setting` | 通过编辑器 API 读取项目设置。 |
| `editor_set_project_setting` | 通过编辑器 API 设置项目设置（自动保存）。 |
| `editor_get_editor_setting` | 读取编辑器首选项值。 |
| `editor_set_editor_setting` | 设置编辑器首选项。 |
| `editor_get_project_directory` | 获取项目 res:// 和 user:// 路径。 |
| `editor_get_input_map` | 通过编辑器 API 读取输入映射。 |
| `editor_add_input_action` | 通过编辑器 API 添加输入操作。 |
| `editor_remove_input_action` | 通过编辑器 API 删除输入操作。 |
| `editor_get_autoload_list` | 通过编辑器 API 列出自动加载单例。 |
| `editor_add_autoload` | 通过编辑器 API 添加自动加载单例。 |
| `editor_remove_autoload` | 通过编辑器 API 删除自动加载单例。 |
| `editor_bake_lightmaps` | 触发光照图烘焙。 |
| `editor_bake_navigation` | 为当前场景中的所有 NavigationRegion 节点烘焙导航网格。 |
| `editor_take_screenshot` | 捕获编辑器视口作为 PNG。 |
| `editor_get_class_list` | 列出所有 Godot 类，可选过滤。 |
| `editor_get_method_list` | 列出 Godot 类的所有方法。 |
| `editor_get_class_property_list` | 列出类的所有编辑器可见属性。 |
| `editor_get_class_signal_list` | 列出 Godot 类的所有信号。 |
| `editor_get_class_doc` | 在浏览器中打开 Godot 类的文档。 |
| `editor_search_help` | 在浏览器中搜索 Godot 文档。 |
| `editor_get_editor_camera` | 获取 3D 编辑器视口摄像机位置。 |
| `editor_set_editor_camera` | 设置 3D 编辑器视口摄像机位置。 |
| `editor_toggle_grid` | 切换 3D 网格可见性。 |
| `editor_toggle_snap` | 切换 3D 对齐模式。 |
| `editor_get_recent_scenes` | 列出最近打开的场景路径。 |
| `editor_simulate_key` | 模拟编辑器中的按键（例如 F5 运行，Ctrl+S 保存）。 |
| `editor_get_plugin_list` | 列出所有已安装的编辑器插件及其启用状态。 |
| `editor_enable_plugin` | 启用已命名的编辑器插件。 |
| `editor_disable_plugin` | 禁用已命名的编辑器插件。 |
| `editor_get_error_list` | 获取当前编辑器错误/日志列表。 |
| `editor_clear_errors` | 清除编辑器错误列表。 |
| `editor_health_check` | 检查 Godot 编辑器插件是否可达。 |
</details>
<details>
<summary><b>🏗️ 场景</b> (22 个工具) — 完整的场景 CRUD + 节点 + 信号 + 变换</summary>
| 工具 | 描述 |
|---|---|
| `read_scene` | 读取 .tscn 场景文件。 |
| `create_scene` | 从模板创建新场景。 |
| `edit_scene` | 对场景应用批量操作。 |
| `list_scenes` | 列出所有 .tscn 场景文件。 |
| `search_scene_content` | 在 .tscn 内容中进行全文搜索。 |
| `scene_dependency_graph` | 分析场景间的依赖关系。 |
| `add_node` | 向场景添加节点。 |
| `remove_node` | 从场景中删除节点。 |
| `modify_node` | 修改节点属性或重命名。 |
| `clone_node` | 在场景中深度克隆节点。 |
| `rename_node` | 在场景中重命名节点。 |
| `attach_script` | 将脚本附加到节点。 |
| `connect_signal` | 连接节点之间的信号。 |
| `disconnect_signal` | 断开信号。 |
| `set_node_position` | 设置节点位置（2D/3D 自动检测）。 |
| `set_node_rotation` | 设置节点旋转（2D/3D）。 |
| `set_node_scale` | 设置节点缩放（2D/3D）。 |
| `transform_node` | 对节点应用变换。 |
| `set_collision_shape` | 为 CollisionShape 节点设置碰撞形状。 |
| `load_sprite` | 将纹理加载到 Sprite2D 节点上。 |
| `list_ui_nodes` | 列出 Control 派生的 UI 节点。 |
| `find_nodes_in_scenes` | 按类型/属性搜索场景中的节点。 |
</details>
<details>
<summary><b>📁 项目</b> (22 个工具) — 配置、输入映射、文件操作、自动加载、验证</summary>
| 工具 | 描述 |
|---|---|
| `list_project_files` | 列出 Godot 项目中的文件和目录。 |
| `read_project_config` | 读取并解析 project.godot。 |
| `write_project_config` | 将配置值写入 project.godot。 |
| `read_export_presets` | 从 export_presets.cfg 读取导出预设。 |
| `read_input_map` | 读取具有键绑定的输入映射。 |
| `write_input_action` | 创建新的输入操作。 |
| `remove_input_action` | 删除输入操作。 |
| `add_input_binding` | 将键/鼠标/手柄绑定添加到操作。 |
| `list_autoloads` | 列出所有自动加载单例。 |
| `add_autoload` | 添加自动加载条目。 |
| `remove_autoload` | 删除自动加载条目。 |
| `search_in_project` | 在项目文件中搜索文本。 |
| `delete_file` | 删除具有 .bak 备份的文件。 |
| `move_file` | 在项目中移动/重命名文件。 |
| `create_directory` | 在项目中创建目录。 |
| `duplicate_scene` | 复制场景文件。 |
| `duplicate_resource` | 复制 .tres 资源。 |
| `generate_project_report` | 生成综合项目概述。 |
| `find_unused_assets` | 查找孤立的项目文件。 |
| `validate_project` | 验证项目中的损坏引用、空 UID。 |
| `list_groups` | 列出场景中的所有节点组。 |
</details>
<details>
<summary><b>📝 脚本</b> (21 个工具) — GDScript/Shader CRUD + 分析 + 注入 + 验证</summary>
| 工具 | 描述 |
|---|---|
| `read_script` | 读取具有行号的脚本文件。 |
| `write_script` | 将内容写入脚本文件。 |
| `create_script` | 从模板创建新脚本。 |
| `list_scripts` | 按类型分组列出所有脚本文件。 |
| `read_script_structure` | 分析 GDScript 结构。 |
| `search_in_scripts` | 在脚本中搜索具有函数上下文。 |
| `validate_script` | 验证 GDScript 常见问题。 |
| `add_script_function` | 将函数追加到 GDScript。 |
| `add_script_signal` | 将信号声明添加到 GDScript。 |
| `add_script_export` | 将 @export 变量添加到 GDScript。 |
| `read_shader` | 读取 .gdshader 文件。 |
| `create_shader` | 从模板创建新的 .gdshader。 |
| `list_shaders` | 列出所有 .gdshader 文件。 |
| `write_shader` | 将内容写入 .gdshader。 |
| `validate_shader` | 验证 .gdshader 的语法问题（shader_type、括号、声明）。 |
| `compile_shader` | 通过 Godot 编辑器或本地验证编译（重新导入） .gdshader。 |
| `list_visual_shaders` | 列出 VisualShader 图形文件。 |
| `read_visual_shader` | 读取 VisualShader 图形。 |
| `read_shader_include` | 读取 .gdshaderinc 文件。 |
| `create_shader_include` | 创建 .gdshaderinc 文件。 |
| `list_shader_includes` | 列出所有 .gdshaderinc 文件。 |
</details>
<details>
<summary><b>🎯 域</b> (11 个工具) — 曲线、渐变、路径、骨骼、反射探针、多网格、噪声纹理</summary>
| 工具 | 描述 |
|---|---|
| `read_curve` | 读取曲线资源。 |
| `create_curve` | 创建曲线 .tres 资源。 |
| `read_gradient` | 读取渐变资源。 |
| `create_gradient` | 创建渐变 .tres 资源。 |
| `list_paths` | 列出场景中的 Path2D/Path3D 节点。 |
| `read_path` | 读取具有曲线点的 Path2D/Path3D 节点。 |
| `list_skeletons` | 列出 Skeleton3D 节点。 |
| `read_skeleton` | 读取 Skeleton3D 骨骼层次结构。 |
| `read_reflection_probe` | 读取反射探针设置。 |
| `read_multi_mesh` | 读取多网格实例设置。 |
| `create_noise_texture` | 创建 NoiseTexture2D/3D .tres。 |
</details>
<details>
<summary><b>🎞️ 动画</b> (10 个工具) — AnimationPlayer/AnimationTree 全流程</summary>
| 工具 | 描述 |
|---|---|
| `list_animations` | 列出 AnimationPlayers 和动画。 |
| `read_animation` | 读取动画轨道和关键帧。 |
| `create_animation` | 创建动画 .tres 资源。 |
| `set_animation_param` | 设置动画参数。 |
| `add_animation_library` | 将动画库添加到播放器。 |
| `add_animation_track` | 将轨道添加到动画。 |
| `set_keyframe` | 在轨道上设置关键帧。 |
| `remove_animation_track` | 从动画中删除轨道。 |
| `read_animation_tree` | 读取具有状态机的 AnimationTree。 |
| `set_animation_tree_param` | 设置 AnimationTree 参数。 |
</details>
<details>
<summary><b>⚙️ Godot 引擎</b> (9 个工具) — 引擎检测、启动、运行、导出、截图</summary>
| 工具 | 描述 |
|---|---|
| `get_godot_version` | 检测已安装的 Godot 版本。 |
| `launch_editor` | 启动 Godot 编辑器与项目。 |
| `run_project` | 运行 Godot 项目。 |
| `stop_project` | 停止所有正在运行的 Godot 进程。 |
| `export_project` | 通过 Godot CLI 预设导出项目。 |
| `capture_screenshot` | 捕获正在运行的游戏的截图。 |
| `monitor_output` | 读取 Godot 进程输出。 |
| `is_editor_running` | 检查 Godot 编辑器是否正在运行。 |
| `list_projects` | 扫描目录中的 Godot 项目。 |
</details>
<details>
<summary><b>🎨 覆盖率</b> (18 个工具) — 网格基元、2D 灯光、VehicleBody、SpringArm、Decal 等</summary>
| 工具 | 描述 |
|---|---|
| `create_mesh_primitive` | 创建 3D 网格资源：盒子、胶囊、圆柱体、平面、球体、环形等（11 种类型）。 |
| `read_light_2d` | 列出具有能量和阴影设置的 PointLight2D/DirectionalLight2D 节点。 |
| `set_light_2d_param` | 在 2D 灯光节点上设置参数。 |
| `create_vehicle_body` | 创建具有 VehicleWheel 节点的 VehicleBody3D 以进行汽车物理模拟。 |
| `read_vehicle_body` | 列出具有轮子数量的 VehicleBody3D 节点。 |
| `create_spring_arm` | 创建 SpringArm3D 以实现平滑的相机跟随。 |
| `read_spring_arm` | 列出具有弹簧长度和碰撞设置的 SpringArm3D 节点。 |
| `read_decal` | 列出具有大小和纹理信息的 Decal 节点。 |
| `read_occluder` | 列出 OccluderInstance3D 和 OcclusionPolygon2D 节点。 |
| `read_marker` | 列出 Marker2D/Marker3D 位置标记，适用于场景。 |
| `read_audio_stream` | 读取音频文件信息：格式、大小、循环、比特率，来自 .import 配置。 |
| `read_audio_listener` | 列出 AudioListener2D/3D 节点以进行空间音频定位。 |
| `create_camera_attributes` | 为 3D 相机景深和自动曝光创建 CameraAttributes（实用或物理）。 |
| `create_sprite_frames` | 创建具有命名动画的 SpriteFrames .tres 资源。 |
| `read_sprite_frames` | 列出 AnimatedSprite 节点及其 SpriteFrames 资源。 |
| `read_soft_body` | 列出具有质量和刚度的 SoftBody3D 节点。 |
| `read_grid_map` | 列出具有单元格大小和网格库引用的 GridMap 节点。 |
| `create_grid_map` | 创建 GridMap 节点以进行 3D 基于图块的关卡设计。 |
</details>
<details>
<summary><b>🔲 节点</b> (8 个工具) — CharacterBody、AnimatedSprite、音频、视频、视差、富文本、容器、选项卡</summary>
| 工具 | 描述 |
|---|---|
| `read_character_body` | 读取 CharacterBody2D/3D 属性。 |
| `read_animated_sprite` | 读取 AnimatedSprite2D/3D 具有动画和帧数据。 |
| `read_audio_player` | 读取 AudioStreamPlayer2D/3D 具有流和播放设置。 |
| `read_video_player` | 读取 VideoStreamPlayer 具有视频流和播放设置。 |
| `read_parallax` | 读取 ParallaxBackground/Parallax2D 具有层配置。 |
| `read_rich_text` | 读取 RichTextLabel 具有 BBCode 内容。 |
| `read_container` | 读取具有子布局信息的容器派生节点。 |
| `read_tab_container` | 读取具有选项卡名称和数量的 TabContainer。 |
</details>
<details>
<summary><b>📦 资源</b> (8 个工具) — .tres CRUD、PBR 材质、主题、模板</summary>
| 工具 | 描述 |
|---|---|
| `read_resource` | 读取 .tres 资源文件。 |
| `list_resources` | 列出所有资源文件。 |
| `create_resource` | 从模板创建资源。 |
| `write_resource` | 将属性写入资源。 |
| `list_materials` | 按类型列出材质。 |
| `read_material` | 读取具有 PBR 格式的材质。 |
| `set_material_param` | 设置单个材质参数。 |
| `read_theme` | 读取具有类型感知分组的主题资源。 |
</details>
<details>
<summary><b>🔊 音频</b> (7 个工具) — 音频总线布局 CRUD、效果、音量</summary>
| 工具 | 描述 |
|---|---|
| `read_audio_bus_layout` | 读取 AudioBusLayout。 |
| `list_audio_files` | 按格式列出音频文件。 |
| `create_audio_bus_layout` | 创建 AudioBusLayout。 |
| `add_audio_bus` | 将音频总线添加到布局。 |
| `remove_audio_bus` | 删除音频总线。 |
| `add_bus_effect` | 将效果添加到音频总线。 |
| `set_bus_volume` | 以 dB 设置总线音量。 |
</details>
<details>
<summary><b>🧩 着色器图</b> (8 个工具) — VisualShader 图形节点添加/删除/连接、参数编辑</summary>
| 工具 | 描述 |
|---|---|
| `create_visual_shader` | 创建新的 VisualShader .tres 图形文件。 |
| `add_shader_graph_node` | 将节点添加到 VisualShader 图形。 40+ 节点类型可用（常量、数学、纹理、效果）。 |
| `remove_shader_graph_node` | 通过索引从 VisualShader 图形中删除节点。 |
| `connect_shader_graph_nodes` | 在 VisualShader 图形中连接两个节点端口。 |
| `disconnect_shader_graph_nodes` | 在 VisualShader 图形中断开两个节点端口的连接。 |
| `set_shader_node_param` | 在 VisualShader 节点上设置参数（常量、表达式、运算符等）。 |
| `list_shader_node_types` | 按类别列出所有 VisualShader 节点类型，并带有输入/输出计数。 |
| `get_shader_node_defaults` | 获取特定 VisualShader 节点类型的默认端口和参数。 |
</details>
<details>
<summary><b>🛠️ 实用工具</b> (6 个工具) — 信号列表、StyleBox、AtlasTexture、弹出窗口、项目图标、凝聚力报告</summary>
| 工具 | 描述 |
|---|---|
| `list_all_signals` | 列出 Godot 类的所有内置信号。 |
| `read_project_icon` | 读取项目图标文件。 |
| `read_stylebox` | 读取主题和场景中的 StyleBox 资源。 |
| `create_atlas_texture` | 从精灵表创建 AtlasTexture .tres。 |
| `list_popups` | 列出场景中的 Popup/PopupMenu/AcceptDialog 节点。 |
| `generate_cohesion_report` | 生成项目代码凝聚力和耦合报告。 |
</details>
<details>
<summary><b>🖼️ 渲染</b> (5 tools) — MeshInstance, Viewport, Area, RayCast/ShapeCast</summary>
| 工具 | 描述 |
|---|---|
| `read_mesh_instance` | 读取带有网格和材质插槽的 MeshInstance3D。 |
| `set_mesh_surface_material` | 在网格表面插槽上设置材质。 |
| `read_viewport` | 读取 Viewport 节点配置。 |
| `read_area` | 读取带有碰撞和重叠设置的 Area2D/Area3D。 |
| `read_raycast` | 读取 RayCast2D/3D 或 ShapeCast2D/3D 配置。 |
</details>
<details>
<summary><b>🌍 环境</b> (4 tools) — Environment .tres 读取/写入 + 预设</summary>
| 工具 | 描述 |
|---|---|
| `read_environment` | 读取 Environment 资源。 |
| `list_environments` | 列出 Environment 资源。 |
| `create_environment` | 从预设创建 Environment。 |
| `set_environment_param` | 设置环境参数。 |
</details>
<details>
<summary><b>🔍 检查器</b> (5 tools) — Camera, Light, Particle 节点检查和编辑</summary>
| 工具 | 描述 |
|---|---|
| `list_cameras` | 列出 Camera 节点。 |
| `read_camera` | 读取相机配置。 |
| `list_lights` | 列出光源节点。 |
| `set_light_param` | 设置光源参数。 |
| `read_particles` | 列出粒子系统。 |
</details>
<details>
<summary><b>⚡ 物理</b> (4 tools) — 物理材质 CRUD，碰撞层名称</summary>
| 工具 | 描述 |
|---|---|
| `list_physics_materials` | 列出物理材质。 |
| `read_physics_material` | 读取物理材质。 |
| `create_physics_material` | 创建物理材质。 |
| `read_collision_layers` | 读取碰撞层名称。 |
</details>
<details>
<summary><b>📥 导入</b> (3 tools) — .import 文件读取/写入和列表</summary>
| 工具 | 描述 |
|---|---|
| `read_import_config` | 读取 .import 文件配置。 |
| `list_import_files` | 按类型列出 .import 文件。 |
| `write_import_config` | 写入导入设置。 |
</details>
<details>
<summary><b>🗺️ 瓦片地图</b> (3 tools) — TileSet 资源解析，TileMapLayer 检查</summary>
| 工具 | 描述 |
|---|---|
| `list_tilesets` | 列出 TileSet 资源。 |
| `read_tileset` | 读取 TileSet 资源。 |
| `read_tilemap` | 读取场景中的 TileMapLayer。 |
</details>
<details>
<summary><b>🧭 导航</b> (3 tools) — 导航区域检查 + 导航网格创建</summary>
| 工具 | 描述 |
|---|---|
| `list_nav_regions` | 列出导航区域节点。 |
| `read_nav_region` | 读取导航区域。 |
| `create_nav_mesh` | 创建导航网格 .tres。 |
</details>
<details>
<summary><b>🌐 翻译</b> (3 tools) — CSV/PO 翻译文件读取/写入</summary>
| 工具 | 描述 |
|---|---|
| `list_translations` | 列出翻译文件。 |
| `read_translation` | 读取翻译文件。 |
| `create_translation` | 创建翻译 CSV。 |
</details>
<details>
<summary><b>🔗 关节</b> (3 tools) — 物理关节创建，参数，列表</summary>
| 工具 | 描述 |
|---|---|
| `create_joint` | 创建物理关节（PinJoint，HingeJoint，SliderJoint 等）。 |
| `set_joint_param` | 在物理关节上设置参数。 |
| `list_joints` | 列出场景中的所有物理关节。 |
</details>
<details>
<summary><b>🆔 UID</b> (3 tools) — 文件 UID 查询，批量更新，缺失 UID 检测</summary>
| 工具 | 描述 |
|---|---|
| `get_uid` | 获取文件的 UID。 |
| `update_project_uids` | 扫描缺失的 UID。 |
| `list_missing_uids` | 列出缺少 UID 的文件。 |
</details>
<details>
<summary><b>📐 2D 几何</b> (2 tools) — CollisionPolygon2D，CollisionShape2D 形状配置</summary>
| 工具 | 描述 |
|---|---|
| `create_collision_polygon` | 创建带有顶点点的 CollisionPolygon2D。 |
| `set_shape_points` | 在 CollisionShape2D 上设置形状点。 |
</details>
<details>
<summary><b>🔄 Diff</b> (2 tools) — 场景和资源比较</summary>
| 工具 | 描述 |
|---|---|
| `diff_scene` | 比较两个场景文件。 |
| `diff_resource` | 比较两个资源文件。 |
</details>
<details>
<summary><b>📋 其他</b> (8 tools) — GDExtension，C#，World3D，GridMap，Texture 等</summary>
| 工具 | 描述 |
|---|---|
| `read_gdextension` | 读取 .gdextension 配置。 |
| `list_csproj` | 列出 C# 项目文件。 |
| `create_world` | 创建 World3D .tres。 |
| `read_texture_info` | 读取纹理资产信息。 |
</details>
---
## 安装
### npx（推荐，无需预安装）
```bash
npx -y @yanhuifair/godot-mcp -p /path/to/your/godot/project
```
### 全局安装
```bash
npm install -g @yanhuifair/godot-mcp
```
### 从源码构建
```bash
git clone https://github.com/yanhuifair/Godot-MCP.git
cd godot-mcp
npm install
npm run build
```
### 环境变量
| 变量 | 描述 |
|---|---|
| `GODOT_PATH` | Godot 二进制文件路径（可选，自动检测） |
Godot 自动检测：`GODOT_PATH` → `/Applications/Godot.app` → `PATH` → snap/flatpak
---
## AI 客户端配置
### VS Code / GitHub Copilot
#### 方法 1：VSIX 扩展（推荐）
```bash
npm run vsix
# → godot-mcp-1.3.0.vsix
code --install-extension godot-mcp-1.3.0.vsix
```
安装后，MCP 服务器会自动注册。Copilot / Cline / Roo Code 会自动发现它 - **无需手动配置**。跳到 [验证设置](#verify-setup)。
#### 方法 2：项目级配置
在 Godot 项目根目录创建 `.vscode/mcp.json`：
```json
{
"mcpServers": {
"godot-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@yanhuifair/godot-mcp", "-p", "."]
}
}
}
```
> 如果您已全局安装（`npm install -g`），请使用 `"command": "godot-mcp"` 并省略 `-y @yanhuifair/godot-mcp` 参数：
>
> ```json
> {
> "mcpServers": {
> "godot-mcp": {
> "type": "stdio",
> "command": "godot-mcp",
> "args": ["-p", "."]
> }
> }
> }
> ```
> 💡 **提示**：将 `.vscode/mcp.json` 提交到您的仓库，以便每个团队成员都能自动获得 MCP 服务器。
#### SSE（服务器发送事件）— HTTP 传输
对于使用 SSE 的远程或基于 Web 的 MCP 客户端：
1. 以 SSE 模式启动服务器：
```bash
npx @yanhuifair/godot-mcp -t sse --port 3000 -p .
```
2. 配置您的 MCP 客户端：
```json
{
"mcpServers": {
"godot-mcp": {
"url": "http://127.0.0.1:3000/sse"
}
}
}
```
#### 流式 HTTP — MCP 2025 传输
对于支持流式 HTTP 规范的现代 MCP 客户端：
1. 以流式 HTTP 模式启动服务器：
```bash
npx @yanhuifair/godot-mcp -t streamable-http --port 3000 -p .
```
2. 配置您的 MCP 客户端：
```json
{
"mcpServers": {
"godot-mcp": {
"url": "http://127.0.0.1:3000/mcp",
"transportType": "streamable-http"
}
}
}
```
#### 同时使用所有传输
同时运行所有三个传输（stdio + SSE + 流式 HTTP）：
```bash
npx @yanhuifair/godot-mcp -t all --port 3000 -p .
```
#### 验证设置
1. 在 VS Code 中打开您的 Godot 项目文件夹
2. 打开 Copilot Chat（`⇧⌘I` / `Ctrl+Shift+I`）
3. 在聊天输入框中查找 🔌 MCP 工具指示器
4. 发送测试消息：
> "列出项目中的所有场景"
如果服务器响应您的项目场景，则表示它正在工作。
#### 启用编辑器插件（实时控制）
对于实时编辑器控制 - 选择节点，播放/停止，撤销/重做，设置断点 - 安装插件（一次性设置）：
```bash
npx @yanhuifair/godot-mcp --install-addons -p .
```
然后在 Godot 编辑器中启用：**项目 → 项目设置 → 插件 → Godot MCP → 启用**。在 **输出** 面板中确认：
```
[Godot MCP] 插件 v1.3.0 已加载 — 在 stdin/stdout 上就绪
```
> 💡 启用插件后，您可以关闭 Godot。MCP 会在您使用编辑器命令时自动启动它。
现在尝试：
> "以 1280x720 运行游戏"
> "选择 Player 节点并显示其属性"
#### 故障排除
| 问题 | 解决方案 |
|---|---|
| 服务器未启动 | 确保 Node.js ≥18：`node -v` |
| "命令未找到" | 使用 `npx` 方法或 `npm install -g @yanhuifair/godot-mcp` |
| 插件在 Godot 中未显示 | 在插件选项卡中单击 **重启**，或重新打开项目 |
| 编辑器进程无法启动 | 确保 Godot 已安装并在 PATH 中，或设置 `GODOT_PATH` |
| 工具在聊天中未出现 | 重新加载 VS Code：`Cmd+Shift+P` → `Developer: Reload Window` |
### 光标
`~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"godot-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@yanhuifair/godot-mcp", "-p", "/path/to/your/godot/project"]
}
}
}
```
或使用全局安装：
```json
{
"mcpServers": {
"godot-mcp": {
"type": "stdio",
"command": "godot-mcp",
"args": ["-p", "/path/to/your/godot/project"]
}
}
}
```
### Claude 桌面版
`~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"godot-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@yanhuifair/godot-mcp", "-p", "/path/to/your/godot/project"]
}
}
}
```
### Windsurf
`~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"godot-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@yanhuifair/godot-mcp", "-p", "/path/to/your/godot/project"]
}
}
}
```
### 本地开发
```json
{
"mcpServers": {
"godot-mcp": {
"type": "stdio",
"command": "node",
"args": ["/path/to/godot-mcp/dist/index.js", "-p", "/path/to/your/godot/project"]
}
}
}
```
---
## 使用示例
### 浏览项目
```
"显示项目结构"
→ list_project_files → 完整的文件树
"生成项目概述报告"
→ generate_project_report → 场景/脚本/着色器/资源统计
"检查项目健康状况"
→ validate_project → 损坏的引用，缺失的 UID
```
### 创建资源
```
"创建一个 2D 平台游戏场景"
→ create_scene → 场景/main.tscn
"创建一个金属材质"
→ create_resource → 材质/metal.tres
→ set_material_param → 金属 = 0.9，粗糙度 = 0.3
```
### 搜索和定位
```
"查找所有 Timer 节点"
→ find_nodes_in_scenes → 跨场景搜索并带有路径
"搜索 _ready 函数"
→ search_in_scripts → 匹配函数上下文
"列出项目中的所有 UI 按钮"
→ list_ui_nodes → 锚点，位置，文本
```
### 运行和调试
```
"以 1280x720 运行游戏并截图"
→ run_project → 启动游戏
→ capture_screenshot → gameplay.png
"捕获游戏窗口并自定义名称"
→ capture_screenshot output_path="gameplay.png" window_title="My Game" delay=2
"停止正在运行的游戏"
→ stop_project → 终止所有 Godot 进程
```
### 脚本操作
```
"分析 player.gd 结构"
→ read_script_structure → 类名，信号，导出，函数
"在 Player 中添加 dash 方法"
→ add_script_function → 安全的方法注入
"验证所有脚本"
→ validate_script → 每文件语法/逻辑检查
```
### 着色器验证和编译
```
"验证 hurricane.gdshader 是否有语法错误"
→ validate_shader → 着色器类型，大括号声明检查
"编译 hurricane 着色器"
→ compile_shader → 通过编辑器插件触发 Godot 的着色器编译器
```
### 编辑动画
```
"显示 player 动画"
→ read_animation → 轨道列表 + 关键帧
"在 idle 动画中添加位置轨道"
→ add_animation_track → track_path=".:position"
"在 0.5s 处设置关键帧"
→ set_keyframe → time=0.5, value="Vector2(100,0)"
```
### 音频设置
```
"显示音频总线布局"
→ read_audio_bus_layout → 总线层次结构，音量，效果
"在 Master 添加混响"
→ add_bus_effect → effect_type="Reverb"
"设置 SFX 总线音量"
→ set_bus_volume → bus_index=2, volume_db=-6.0
### 场景编辑
```
"在 Player 下添加 Timer"
→ add_node → type=Timer, name=Cooldown
"克隆 Enemy 节点为 Enemy2"
→ clone_node → clone_source="Main/Enemy", name="Enemy2"
"连接 entered_signal"
→ connect_signal → from_node="Player", signal="entered", method="_on_entered"
```
### 项目结构
```
godot-mcp/
├── src/
│ ├── index.ts # 命令行接口入口
│ ├── server.ts # MCP 服务器核心
│ ├── tools/ # 33 个处理程序文件
│ │ ├── register.ts # 集中注册（281 个工具）
│ │ ├── project.ts # 项目工具
│ │ ├── scene.ts # 场景工具
│ │ ├── script.ts # 脚本 + 着色器工具
│ │ ├── editor.ts # 实时编辑器工具
│ │ ├── resource.ts # 资源/材质/主题
│ │ ├── godot.ts # 引擎控制
│ │ ├── animation.ts # 动画管道
│ │ ├── audio.ts # 音频总线
│ │ ├── environment.ts # 环境资源
│ │ ├── physics.ts # 物理材质
│ │ ├── import.ts # 导入配置
│ │ ├── inspector.ts # 节点检查器
│ │ ├── shader_graph.ts # VisualShader 图形
│ │ ├── tileset.ts # TileMap/TileSet
│ │ ├── navigation.ts # 导航网格
│ │ ├── translation.ts # 翻译文件
│ │ ├── diff.ts # 文件比较
│ │ ├── texture.ts # 纹理信息
│ │ ├── extension.ts # GDExtension/C#
│ │ ├── uid.ts # 文件 UID
│ │ ├── joint.ts # 物理关节
│ │ ├── geometry.ts # 2D 几何形状
│ │ ├── rendering.ts # 网格/视口/射线投射
│ │ ├── domain.ts # 曲线/渐变/骨骼/路径
│ │ ├── nodes.ts # 节点特定检查器
│ │ ├── utility.ts # 实用工具
│ │ └── coverage.ts # 网格/2D 灯光/车辆等
│ ├── parsers/
│ │ ├── scene_parser.ts # .tscn 解析器
│ │ ├── resource_parser.ts # .tres 解析器
│ │ ├── config_parser.ts # project.godot 解析器
│ │ └── parser_helpers.ts # 共享解析实用工具
│ └── utils/
│ ├── types.ts # 类型定义
│ ├── file_utils.ts # 文件系统操作
│ ├── godot_cli.ts # Godot 命令行接口
│ ├── registry.ts # 工具注册表
│ ├── errors.ts # 错误代码
│ └── cache.ts # 文件缓存
├── addons/
│ └── godot_mcp/ # Godot 编辑器插件
│ ├── plugin.cfg # 插件元数据
│ └── plugin.gd # 标准输入读取器 + 命令处理程序
├── dist/ # 编译输出
├── test/ # 测试套件
├── package.json
└── README.md
```
---
## 支持的格式
| 格式 | 扩展名 | 支持 |
|---|---|---|
| 场景 | `.tscn` | ✅ 读取、写入、创建、编辑（7 个操作） |
| 脚本 | `.gd` | ✅ 读取、写入、创建、验证、分析 |
| 脚本 | `.cs` | ✅ 读取、写入、创建 |
| 着色器 | `.gdshader` | ✅ 读取、写入、创建 |
| 着色器包含 | `.gdshaderinc` | ✅ 读取、写入、创建 |
| VisualShader | `.tres` | ✅ 读取、列表、图形编辑 |
| 资源 | `.tres` | ✅ 读取、写入、创建（14 个模板） |
| 资源 | `.res` | ❌ 不支持（二进制） |
| 配置 | `project.godot` | ✅ 读取、写入 |
| 配置 | `export_presets.cfg` | ✅ 读取 |
| 导入 | `.import` | ✅ 读取、写入 |
| 环境 | `.tres` | ✅ 读取、写入、创建（4 个预设） |
| 动画 | `.tres` / `.tscn` | ✅ 读取、创建、修改参数 |
| 音频总线 | `.tres` | ✅ 读取、写入、创建 |
| 物理材质 | `.tres` | ✅ 读取、写入、创建 |
| TileSet | `.tres` | ✅ 读取、列表 |
| 翻译 | `.csv` / `.po` | ✅ 读取、创建 |
---
## 开发
```bash
npm install # 安装依赖
npm run build # 构建 TypeScript → dist/
npm run dev # 开发模式（tsx 热重载）
npm test # 运行 138 个测试
npm run test:watch # 监视模式
```
### 命令行选项
| 标志 | 描述 |
|---|---|
| `-p, --project-path` | Godot 项目根路径 |
| `-g, --godot-path` | Godot 二进制路径（可选） |
| `--install-addons` | 将 addons/godot_mcp 复制到目标 Godot 项目 |
| `-h, --help` | 显示帮助 |
### 技术栈
- **运行时**: Node.js ≥18
- **语言**: TypeScript 5.5
- **MCP SDK**: @modelcontextprotocol/sdk ^1.29
- **模式**: Zod ^3.24
- **测试**: Vitest ^2.0
- **传输**: stdio
---
## 构建 VSIX
```bash
npm run vsix
# → godot-mcp-1.3.0.vsix
```
参阅 [VS Code 设置](#vs-code--github-copilot) 以了解安装和使用方法。
---
## 限制
- 不支持二进制 `.res` 文件 — 使用 `.tres`（文本格式）
- Godot 命令行工具需要 Godot 引擎二进制文件
- 截图依赖于操作系统原生工具
- `edit_scene` 使用 `.tscn` 的 AST 操纵；复杂的重构可能需要手动验证
---
## 许可证
MIT
连接信息
猜你喜欢
暂无推荐服务器