内容
# Godot MCP
**语言:** | [简体中文](README.zh.md)
开源的Godot MCP服务器，允许AI助手（Claude Code、Cursor、Codex等）直接通过[模型上下文协议（MCP）](https://modelcontextprotocol.io/)控制Godot 4编辑器。
```
AI客户端 ←—stdio/MCP—→ Node.js服务器 ←—WebSocket:6505—→ Godot编辑器插件
```
## 概述
| 组件 | 角色 |
|-----------|------|
| **Godot插件** | WebSocket客户端，接收JSON-RPC请求，通过编辑器API执行命令 |
| **Node.js MCP服务器** | 与AI客户端通信；运行WebSocket服务器（默认端口6505），转发工具调用 |
| **命令路由器** | `command_router.gd`聚合了24个命令模块，共**173**个处理程序 |
| **运行时服务** | 3个自动加载项（`MCPRuntimeBridge` / `MCPInputBridge` / `MCPScreenshotBridge`）使用`user://` IPC进行游戏内检查、输入模拟和截图 |
### 核心功能
- **撤销/重做集成** — 节点添加/删除/编辑和属性更改通过编辑器撤销栈进行
- **智能类型解析** — 字符串如`Vector2(100, 200)`、 `#ff0000`、`Color(1,0,0)`自动转换为相应类型
- **重新连接** — 插件侧的指数退避（1s → 60s）
- **心跳** — 双向ping/pong保持WebSocket连接
- **JSON-RPC 2.0** — Godot插件和Node.js服务器之间的标准协议
## 工具类别
**173个MCP工具**，涵盖 **26个类别**：
| 类别 | 工具 | 亮点 |
|----------|-------|------------|
| 项目 | 7 | 项目信息、文件搜索、UID转换、项目设置 |
| 场景 | 10 | 场景树、创建/删除/实例化场景、播放/停止、`@export`变量 |
| 节点 | 14 | CRUD、属性、信号、组、资源附件 |
| 脚本 | 8 | 脚本CRUD、附加、验证、全文搜索 |
| 编辑器 | 13 | 编辑器/游戏截图、相机控制、错误日志、截图差异、自动关闭对话框 |
| 输入 | 7 | 键盘/鼠标/动作模拟、输入映射（包括死区） |
| 运行时 | 20 | 游戏内场景树、属性、信号监视、记录/回放、UI点击、导航 |
| 动画 | 6 | 轨道、关键帧、AnimationPlayer CRUD |
| TileMap | 6 | 单元格读写、矩形填充、已使用单元格查询 |
| 主题/UI | 7 | 主题创建、Control布局、颜色/字体/StyleBox覆盖 |
| 性能分析 | 2 | FPS、内存、绘制调用、物理监视器 |
| 批量/重构 | 9 | 批量添加节点、批量属性更新、跨场景编辑、依赖/循环检测 |
| 着色器 | 6 | 着色器CRUD、材质分配、参数读写 |
| 导出 | 3 | 导出预设列表、导出命令生成 |
| 资源 | 6 | `.tres`读写、自动加载注册/删除 |
| 物理 | 6 | 碰撞体、物理层（包括层名称解析）、RayCast |
| 3D场景 | 6 | 网格实例、相机、灯光、环境、GridMap |
| 粒子 | 5 | GPU粒子、材质、渐变、预设（火/烟/火花） |
| 导航 | 6 | 导航区域/代理、网格烘焙、路径查找 |
| 音频 | 6 | 音频播放器、总线、效果 |
| AnimationTree | 8 | 状态机、过渡、混合树、参数 |
| 分析 | 4 | 场景复杂度、信号流、未使用资源、项目统计 |
| 测试/QA | 5 | 测试场景、断言、压力测试 |
| Android | 4 | adb设备列表、APK导出/部署、预设详情 |
<details>
<summary>展开查看所有173个工具名称</summary>
**项目：** `get_project_info` · `get_filesystem_tree` · `search_files` · `get_project_settings` · `set_project_setting` · `uid_to_project_path` · `project_path_to_uid`
**场景：** `get_scene_tree` · `get_scene_file_content` · `create_scene` · `open_scene` · `delete_scene` · `add_scene_instance` · `play_scene` · `stop_scene` · `save_scene` · `get_scene_exports`
**节点：** `add_node` · `delete_node` · `duplicate_node` · `move_node` · `update_property` · `get_node_properties` · `add_resource` · `set_anchor_preset` · `rename_node` · `connect_signal` · `disconnect_signal` · `get_node_groups` · `set_node_groups` · `find_nodes_in_group`
**脚本：** `list_scripts` · `read_script` · `create_script` · `edit_script` · `attach_script` · `get_open_scripts` · `validate_script` · `search_in_files`
**编辑器：** `get_editor_errors` · `get_editor_screenshot` · `get_game_screenshot` · `execute_editor_script` · `clear_output` · `get_signals` · `reload_plugin` · `reload_project` · `get_output_log` · `get_editor_camera` · `set_editor_camera` · `set_auto_dismiss` · `compare_screenshots`
**输入：** `simulate_key` · `simulate_mouse_click` · `simulate_mouse_move` · `simulate_action` · `simulate_sequence` · `get_input_actions` · `set_input_action`
**运行时：** `get_game_scene_tree` · `get_game_node_properties` · `set_game_node_property` · `execute_game_script` · `capture_frames` · `monitor_properties` · `start_recording` · `stop_recording` · `replay_recording` · `find_nodes_by_script` · `get_autoload` · `batch_get_properties` · `find_ui_elements` · `click_button_by_text` · `wait_for_node` · `find_nearby_nodes` · `navigate_to` · `move_to` · `watch_signals`
**动画：** `list_animations` · `create_animation` · `add_animation_track` · `set_animation_keyframe` · `get_animation_info` · `remove_animation`
**TileMap：** `tilemap_set_cell` · `tilemap_fill_rect` · `tilemap_get_cell` · `tilemap_clear` · `tilemap_get_info` · `tilemap_get_used_cells`
**主题/UI：** `create_theme` · `set_theme_color` · `set_theme_constant` · `set_theme_font_size` · `set_theme_stylebox` · `get_theme_info` · `setup_control`
**性能分析：** `get_performance_monitors` · `get_editor_performance`
**批量/重构：** `find_nodes_by_type` · `find_signal_connections` · `batch_set_property` · `find_node_references` · `get_scene_dependencies` · `cross_scene_set_property` · `find_script_references` · `detect_circular_dependencies` · `batch_add_nodes`
**着色器：** `create_shader` · `read_shader` · `edit_shader` · `assign_shader_material` · `set_shader_param` · `get_shader_params`
**导出：** `list_export_presets` · `export_project` · `get_export_info`
**资源：** `read_resource` · `edit_resource` · `create_resource` · `get_resource_preview` · `add_autoload` · `remove_autoload`
**物理：** `setup_physics_body` · `setup_collision` · `set_physics_layers` · `get_physics_layers` · `get_collision_info` · `add_raycast`
**3D场景：** `add_mesh_instance` · `setup_camera_3d` · `setup_lighting` · `setup_environment` · `add_gridmap` · `set_material_3d`
**粒子：** `create_particles` · `set_particle_material` · `set_particle_color_gradient` · `apply_particle_preset` · `get_particle_info`
**导航：** `setup_navigation_region` · `setup_navigation_agent` · `bake_navigation_mesh` · `set_navigation_layers` · `get_navigation_info` · `get_navigation_path`
**音频：** `add_audio_player` · `add_audio_bus` · `add_audio_bus_effect` · `set_audio_bus` · `get_audio_bus_layout` · `get_audio_info`
**AnimationTree：** `create_animation_tree` · `get_animation_tree_structure` · `set_tree_parameter` · `add_state_machine_state` · `remove_state_machine_state` · `add_state_machine_transition` · `remove_state_machine_transition` · `set_blend_tree_node`
**分析：** `analyze_scene_complexity` · `analyze_signal_flow` · `find_unused_resources` · `get_project_statistics`
**测试/QA：** `run_test_scenario` · `assert_node_state` · `assert_screen_text` · `run_stress_test` · `get_test_report`
**Android：** `list_android_devices` · `deploy_to_android` · `get_android_build_info` · `get_android_preset_info`
</details>
## 项目结构
```
godot-mcp/
├── addons/godot_mcp/ # Godot编辑器插件（复制到您的项目中）
│ ├── plugin.gd # 插件入口；注入自动加载项
│ ├── plugin.cfg
│ ├── websocket_client.gd # WebSocket客户端 + JSON-RPC调度
│ ├── command_router.gd # 命令路由器；注册所有处理程序
│ ├── commands/ # 24个命令模块（173个工具实现）
│ │ ├── base_commands.gd # 基础类：撤销、运行时IPC、截图等
│ │ ├── project_commands.gd
│ │ ├── scene_commands.gd
│ │ ├── node_commands.gd
│ │ ├── script_commands.gd
│ │ ├── editor_commands.gd
│ │ ├── input_commands.gd
│ │ ├── runtime_commands.gd
│ │ ├── animation_commands.gd
│ │ ├── tilemap_commands.gd
│ │ ├── theme_commands.gd
│ │ ├── profiling_commands.gd
│ │ ├── batch_commands.gd
│ │ ├── shader_commands.gd
│ │ ├── export_commands.gd
│ │ ├── resource_commands.gd
│ │ ├── physics_commands.gd
│ │ ├── scene_3d_commands.gd
│ │ ├── particle_commands.gd
│ │ ├── navigation_commands.gd
│ │ ├── audio_commands.gd
│ │ ├── animation_tree_commands.gd
│ │ ├── analysis_commands.gd
│ │ ├── test_commands.gd
│ │ └── android_commands.gd
│ ├── services/ # 运行时自动加载服务
│ │ ├── mcp_runtime_bridge.gd # 游戏内场景树/属性/脚本执行
│ │ ├── mcp_input_bridge.gd # 输入事件队列
│ │ └── mcp_screenshot_bridge.gd
│ └── utils/
│ ├── type_parser.gd # Vector2/Color类型解析
│ ├── node_utils.gd
│ └── resource_utils.gd
├── server/ # Node.js MCP服务器
│ ├── src/
│ │ ├── index.ts # MCP stdio入口
│ │ ├── godot-bridge.ts # WebSocket服务器 + JSON-RPC
│ │ ├── tools.ts # 工具注册
│ │ └── tool-manifest.ts # 173个工具定义（名称/描述/参数）
│ └── build/index.js # 构建输出（MCP入口点）
├── example/ # 示例Godot项目
├── .mcp.json.example # 示例MCP客户端配置
├── README.md # 英文文档（默认）
└── README.zh.md # 中文文档
```
## 要求
- **Godot** 4.4+
- **Node.js** 18+
- 任意支持MCP的客户端：Claude Code、Cursor、Codex CLI、Cline、Windsurf等
## 使用方法
### 1. 安装Godot插件
将`addons/godot_mcp/`复制到您的Godot项目的`addons/`目录中：
```bash
cp -r addons/godot_mcp /path/to/your-game/addons/
```
在Godot中启用它：**项目 → 项目设置 → 插件 → Godot MCP → 启用**
> 启用插件会注入3个自动加载项（`MCPRuntimeBridge`等）；当插件被禁用时，它们会被移除。
### 2. 构建MCP服务器
```bash
cd server
npm install
npm run build
```
构建后的入口点是`server/build/index.js`。
### 3. 配置AI客户端
在您的MCP配置文件中添加以下内容（**替换路径为实际路径**）：
| 客户端 | 配置位置 |
|--------|-----------------|
| Claude Code | 项目根目录下的`.mcp.json` |
| Cursor | 设置 → MCP，或`~/.cursor/mcp.json` |
| Codex CLI | `~/.codex/config.toml`中的MCP部分 |
| Cline / Roo Code | 扩展程序中的MCP设置 |
```json
{
"mcpServers": {
"godot-mcp": {
"command": "node",
"args": ["D:/godot-mcp/server/build/index.js"],
"env": {
"GODOT_MCP_PORT": "6505"
}
}
}
}
```
另请参阅存储库中的`.mcp.json.example`。
### 4. 开始使用
1. **首先**，在Godot中打开您的项目（启用插件）
2. 启动您的AI客户端并确认`godot-mcp` MCP服务器已连接
3. 请求AI操作编辑器，例如：
- "获取当前场景树"
- "在根节点下添加一个名为Player的CharacterBody2D"
- "创建GDScript并将其附加到Player"
- "播放当前场景，然后捕获游戏截图"
- "在TileMap上填充草地"
### 5. 示例项目
`example/`目录包含一个可运行的演示项目：
```bash
godot --editor example/project.godot
```
## 工作原理
1. AI客户端通过**stdio**调用MCP工具（例如`add_node`）
2. Node.js服务器将请求转换为**JSON-RPC**，并通过**WebSocket**发送到Godot插件
3. 插件的`command_router`调度到匹配的处理程序，该处理程序调用**EditorInterface**和相关API
4. 结果通过相同的路径返回到AI客户端
**运行时工具**（例如`get_game_scene_tree`）还需要：
- 编辑器处于**播放**模式
- 游戏进程加载`MCPRuntimeBridge`自动加载项，并写入`user://mcp_runtime_req.json`的响应
## 添加工具
要添加新的MCP工具：
1. 在`addons/godot_mcp/commands/`下创建或编辑命令类，并在`get_commands()`中注册处理程序
2. 将脚本路径添加到`command_router.gd`中的`COMMAND_MODULES`数组
3. 将工具名称、描述和参数模式添加到`server/src/tool-manifest.ts`中的`TOOL_DEFINITIONS`
然后重建服务器：
```bash
cd server && npm run build
```
## 已知限制
- **Android工具**：`list_android_devices`运行`adb devices`；`deploy_to_android`使用无头Godot导出和adb安装（需要Android导出预设和adb在PATH上）
- **运行时工具**：首先调用`play_scene`；游戏进程必须加载`MCPRuntimeBridge`自动加载项；`watch_signals`在游戏运行时监听指定节点的信号发射
- **跨场景批量编辑**（`cross_scene_set_property`）：修改内存中的场景实例 — 手动保存受影响的场景文件
- 一些编辑器API可能在不同的Godot小版本中有所不同；**4.4+** 版本推荐
## 许可证
MIT
