内容
# Godot 统一 MCP 服务器
一个强大的 **模型上下文协议（MCP）** 服务器，直接连接 AI 代理到 **Godot 引擎**。它统一了四种不同的功能到一个接口中：
1. **编辑器控制**：直接在编辑器中操控场景、节点、脚本和资源。
2. **游戏交互**：与正在运行的游戏进行交互（截图、输入模拟、运行时场景树）。
3. **调试（DAP）**：设置断点、检查变量和逐行调试。
4. **代码智能（LSP）**：自动补全、跳转到定义和符号搜索。
## 功能
* **零配置注入**：在通过此服务器启动 Godot 项目时，自动注入必要的桥接插件。无需手动安装附加组件。
* **实例管理**：同时启动、监控和控制多个 Godot 编辑器实例。
* **端口隔离**：自动为每个实例管理 LSP、DAP 和 HTTP 桥接的端口，以防止冲突。
* **恢复能力**：在服务器重启后恢复会话，并处理外部进程监控。
* **上下文感知**：工具可以针对特定实例或默认为活动实例。
## 先决条件
* **Python**（3.11 或更高版本）和 [uv](https://docs.astral.sh/uv/)（推荐）或 pip
* **Godot 引擎（4.x）** 已安装并可在系统 PATH 中使用（或在启动时提供绝对路径）。
## 安装
1. 克隆此仓库：
```bash
git clone <repo-url>
cd godot-mcp
```
2. 安装依赖项：
```bash
uv venv && uv pip install -e .
```
## 配置（Claude Desktop）
将服务器添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"godot": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/godot-mcp", "godot-mcp-server"]
}
}
}
```
## 使用
连接到您的代理（例如 Claude）后：
1. **启动项目**：
> "为位于 /home/user/my_game 的项目启动 Godot"
服务器将：
* 将 `godot_mcp_bridge` 插件注入到项目中。
* 配置 `project.godot` 以启用插件和自动加载。
* 启动 Godot 编辑器进程，并使用专用端口。
2. **与编辑器交互**：
> "获取当前场景的场景树"
> "将脚本附加到 Player 节点"
3. **运行和测试**：
> "启动游戏"
> "等待 5 秒并截图"
4. **调试**：
> "在 player.gd 的第 10 行设置断点"
> "恢复执行"
> "跳过当前行"
## 工具类别
### 实例管理
* `godot_launch`：启动新的编辑器实例。
* `godot_list_instances`：查看正在运行的项目。
* `godot_switch_instance`：切换活动焦点。
* `godot_terminate`：关闭实例。
* `godot_adopt_instance`：连接到外部启动的 Godot（需要插件已存在）。
### 编辑器工具（`godot_scene_*`、`godot_node_*` 等）
* 管理场景（加载、保存、获取树）。
* 管理节点（创建、删除、重命名、属性）。
* 管理脚本（附加、读取源代码）。
* 项目设置和资源。
### 游戏桥接（`godot_game_*`）
* `godot_game_play` / `stop`：从编辑器控制游戏执行。
* `godot_game_screenshot`：捕获游戏视图（保存到磁盘以保留上下文）。
* `godot_game_scene_tree`：检查运行时节点层次结构。控制节点包括 `screen_rect`（视口坐标）和 Node2D 节点包括 `screen_position`，以便您查看事物在屏幕上的实际位置。
* `godot_game_click`：通过场景路径点击节点（通过所有画布变换解析其屏幕中心）或显式视口 x/y。发送悬停 + 按压 + 释放，以便 GUI 按钮、 `_gui_input` 和 `mouse_entered` 全部触发。
* `godot_game_send_sequence`：模拟原始键盘/鼠标/游戏手柄事件序列，带有延迟（通过 `mouse_motion` 和 `button_mask` 进行鼠标拖动）。
### 调试（`godot_dap_*`、`godot_debugger_*`）和 LSP（`godot_lsp_*`）
* 断点和流程控制：`godot_dap_set_breakpoint`、`godot_debugger_resume`、`godot_debugger_step_over` / `step_into`。
* 检查（适用于断点和运行时错误，如 `assert(false)`）：`godot_dap_stack_trace`、`godot_dap_scopes`、`godot_dap_variables`、`godot_dap_evaluate`。这些自动连接 — 当游戏在错误行暂停时，`godot_debugger_sessions` 报告暂停及其堆栈，您可以检查帧/变量和评估表达式，无需任何预先设置。
* LSP：自动补全、跳转到定义、诊断、悬停、文档符号。
### 编辑器对话框（`godot_editor_*`）
* `godot_editor_dialogs`：列出阻止编辑器的模态对话框（一个操作似乎无效果可能会卡在警报后面）。
* `godot_editor_dialog_dismiss`：接受或取消对话框以取消阻止。
## 提示和资源
除了工具外，服务器还公开 MCP **资源**（只读状态，在 Claude Code 中可 @-提及）：
* `godot://instances` — 正在运行的实例及其端口和状态
* `godot://active/scene-tree` — 活动编辑器实例的场景树
* `godot://active/logs` — 最近的编辑器输出
* `godot://active/screenshot` — 运行中的游戏的实时 PNG（由客户端原生渲染，无需磁盘往返）
和 MCP **提示**（引导工作流，如 Claude Code 中的 `/mcp__godot__playtest` 命令）：
* `debug_breakpoint(project_path, script_path, line)` — 完整的断开并检查序列：启动、DAP 连接、断点、播放、触发、轮询、步骤/恢复
* `playtest(project_path, scene_mode)` — 启动、播放、通过截图/场景树观察、用 `godot_game_click` 交互、报告发现
## 故障排除
* **大截图**：截图自动保存到磁盘（`./screenshot_*.png`），并将路径返回给代理，以避免上下文窗口溢出。
* **端口**：服务器使用从 6005（LSP）开始的端口，6006（DAP），8765（编辑器），8766（游戏），并为每个新实例递增 10。确保这些端口是空闲的。
* **符号搜索**：`godot_lsp_search_symbols`（`workspace/symbol`）不受 Godot 4.6 语言服务器的支持（`workspaceSymbolProvider: false`）；改为使用 `godot_lsp_list_symbols` 每个文件。
## 许可证
MIT
