内容
# Godot MCP 工具包 v3.0
[](https://opensource.org/licenses/MIT)
[](https://godotengine.org)
[](https://nodejs.org)
**55+ 工具**，用于 AI 辅助的 Godot 游戏开发。适用于 Claude、Cursor、Cline、opencode 及任何与 MCP 兼容的客户端。
## 功能
| 类别 | 工具 | 描述 |
|----------|-------|-------------|
| **场景** | 7 | 创建/编辑场景，添加/删除节点，加载精灵，保存，比较 |
| **脚本** | 8 | 读取/写入/分析 GDScript，从模板创建，重构，查找引用 |
| **项目** | 7 | 设置，场景树，验证，列出项目/场景，分析依赖 |
| **资产** | 3 | 导入纹理，模型，音频 |
| **UID** | 2 | 获取/重新生成资源 UID |
| **信号** | 6 | 连接/断开/列出/发出信号，分析流程 |
| **性能** | 6 | 分析场景/脚本，内存分析，检测瓶颈 |
| **着色器** | 6 | 编辑/创建/优化着色器和材质 |
| **动画** | 8 | 创建/编辑/动画，轨道，关键帧，导出 |
| **导出** | 4 | 网格库，导出预设，快速/完整测试 |
| **系统** | 6 | 版本，状态，启动编辑器，运行/停止项目，调试输出 |
## 快速开始
### 1. 克隆并配置
```bash
git clone https://github.com/DuskHound/godot-mcp-toolkit.git
cd godot-mcp-toolkit
```
### 2. 复制到您的 Godot 项目
```bash
cp -r src/addons/godot_mcp /path/to/your/godot/project/addons/
```
### 3. 配置 MCP 客户端
将以下内容添加到您的 MCP 客户端配置（`.mcp.json` 或 Claude Desktop 设置）：
```json
{
"mcpServers": {
"godot-mcp": {
"command": "node",
"args": ["path/to/godot-mcp-toolkit/src/mcp/godot_mcp.js"],
"env": {
"GODOT_PATH": "C:\\Path\\To\\Godot.exe",
"PROJECT_PATH": "C:\\Path\\To\\Your\\Godot\\Project"
}
}
}
}
```
## 工具参考
### 场景
| 工具 | 描述 |
|------|-------------|
| `create_scene` | 创建具有根节点类型的场景 |
| `add_node` | 添加具有属性的子节点 |
| `edit_node` | 编辑节点属性 |
| `remove_node` | 删除节点 |
| `load_sprite` | 加载纹理到精灵上 |
| `save_scene` | 保存场景到路径 |
| `compare_scenes` | 比较两个场景 |
### 脚本
| 工具 | 描述 |
|------|-------------|
| `read_script` | 读取文件（快速，静态） |
| `edit_script` | 写入/编辑文件 |
| `create_script` | 从模板创建（node2d，characterbody2d，autoload，state_machine 等） |
| `list_scripts` | 列出所有 .gd 文件 |
| `analyze_script` | 获取指标（函数，类，信号） |
| `find_script_references` | 搜索整个项目中的符号引用 |
| `refactor_rename` | 重命名文件中的符号 |
| `refactor_extract_method` | 提取行到新方法 |
### 项目
| 工具 | 描述 |
|------|-------------|
| `get_project_info` | 名称，主要场景，autoloads |
| `get_project_settings` | 完整的 project.godot 设置 |
| `list_projects` | 在目录中查找 Godot 项目 |
| `list_scenes` | 列出所有 .tscn 文件 |
| `get_scene_tree` | 节点层次结构为 JSON |
| `validate_project` | 检查丢失的文件，损坏的 autoloads |
| `analyze_dependencies` | 场景资产依赖 |
### 信号
| 工具 | 描述 |
|------|-------------|
| `connect_signal` | 连接信号源→目标 |
| `disconnect_signal` | 删除信号连接 |
| `list_signals` | 列出场景中的所有信号 |
| `emit_signal` | 测试信号 |
| `get_signal_connections` | 映射所有连接 |
| `analyze_signal_flow` | 信号流程图 |
### 性能
| 工具 | 描述 |
|------|-------------|
| `profile_scene` | 节点数，绘制调用估计 |
| `analyze_performance` | 项目范围的性能扫描 |
| `get_performance_report` | 完整报告 |
| `profile_script` | 脚本执行配置文件 |
| `analyze_memory_usage` | 内存分析 |
| `detect_bottlenecks` | 查找慢速点 |
### 着色器和材质
| 工具 | 描述 |
|------|-------------|
| `edit_shader` | 编辑 .gdshader 文件 |
| `create_material` | 创建 .tres 材质 |
| `edit_material` | 设置材质属性 |
| `list_shaders` | 列出所有着色器 |
| `create_shader` | 新着色器文件 |
| `optimize_shader` | 优化建议 |
### 动画
| 工具 | 描述 |
|------|-------------|
| `create_animation` | 新动画 |
| `edit_animation` | 编辑动画参数 |
| `list_animations` | 列出动画 |
| `create_animation_library` | 新库 |
| `add_animation_track` | 添加轨道 |
| `edit_keyframe` | 编辑关键帧数据 |
| `play_animation` | 预览动画 |
| `export_animation` | 导出动画数据 |
### 导出和测试
| 工具 | 描述 |
|------|-------------|
| `export_mesh_library` | 场景→网格库 |
| `get_export_presets` | 列出预设 |
| `quick_test` | 10 秒无头测试 |
| `full_test` | 60 秒全面测试 |
## 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `GODOT_PATH` | Godot 可执行文件路径 | 自动检测 |
| `PROJECT_PATH` | Godot 项目路径 | 当前目录 |
| `DEBUG` | 启用调试日志 | `false` |
| `READ_ONLY_MODE` | 仅分析，无写入 | `false` |
## 架构
```
AI 客户端（Claude，Cursor，opencode）
↕ stdio（MCP 协议）
Node.js MCP 服务器（godot_mcp.js）
↕ 无头 Godot 启动
GDScript 操作（godot_operations.gd）
↕ Godot 引擎 API
您的项目
```
## 安全
- 路径遍历保护
- 输入净化（空字节，特殊字符）
- 节点类型白名单
- CI/CD 只读模式
- 有界输出缓冲区
- 进程生命周期管理
## 许可证
MIT
---
由 DuskHound 为 Godot 社区制作。
