内容
# Godot MCP
Godot MCP 是一个用于控制和检查 Godot 4.4+ 编辑器项目的模型上下文协议（MCP）服务器，适用于与 MCP 兼容的 AI 客户端。
集成了两个部分：
- 一个 Node.js MCP 服务器，通过 stdio 与 AI 客户端通信。
- 一个 Godot 编辑器插件，监听本地 WebSocket 端口并执行编辑器命令。
```text
MCP 客户端
<-> stdio
Node.js MCP 服务器
<-> ws://127.0.0.1:6505
Godot 编辑器插件
<-> Godot 编辑器 API
```
## 功能
- 场景、节点、脚本、资源、项目、编辑器、文件、信号、运行时、调试、动画、着色器、物理、UI、音频、照明、粒子、导入/导出和 ClassDB 工具。
- 用于 GDScript、场景架构、信号、物理、网络、导出等的 Godot 开发技能模块。
- 可搜索的开源 Godot 项目示例引用。
- 用于项目信息、设置、当前场景、编辑器状态、控制台输出、运行时状态和 ClassDB 查询的 MCP 资源。
- 一个 `godot_connection_status` 健康工具，用于在运行编辑器命令之前检查桥接状态。
## 要求
- Node.js 18 或更新版本。
- npm。
- Godot 4.4 或更新版本。
- 支持 stdio 服务器的 MCP 客户端。
## 安装
```bash
git clone <仓库网址>
cd godot-mcp
npm run setup
```
然后将 Godot 插件安装到您要控制的项目中：
```bash
cp -R addons/godot_mcp /路径/到/您的godot项目/addons/
```
在 Godot 中打开项目，并从以下位置启用 `Godot MCP`：
```text
项目 -> 项目设置 -> 插件
```
插件默认监听 `127.0.0.1:6505`。
## MCP 客户端配置
将您的 MCP 客户端指向已构建的服务器：
```json
{
"mcpServers": {
"godot": {
"command": "node",
"args": ["/绝对路径/到/godot-mcp/server/dist/index.js"]
}
}
}
```
在更改 MCP 客户端配置后，请重新启动它。
## 验证连接
1. 打开 Godot 项目，确保插件已启用。
2. 启动或重启您的 MCP 客户端。
3. 运行 `godot_connection_status` MCP 工具。它应该报告 `"connected": true`。
4. 运行 `project_get_info`。它应该返回打开的 Godot 项目的元数据。
如果 `godot_connection_status` 报告 `false`，请检查：
- Godot 已打开并启用了插件。
- 没有其他进程正在使用端口 `6505`。
- MCP 服务器正在使用与插件相同的宿主和端口。
- 您的 MCP 客户端在运行 `npm run setup` 后指向 `server/dist/index.js`。
## 配置
Node 桥接可以使用环境变量进行配置：
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `GODOT_WS_HOST` | `127.0.0.1` | Godot 插件监听的宿主。 |
| `GODOT_WS_PORT` | `6505` | Godot 插件使用的 WebSocket 端口。 |
| `GODOT_RECONNECT_ATTEMPTS` | `5` | 桥接连接断开后的重新连接尝试次数。 |
| `GODOT_RECONNECT_DELAY_MS` | `2000` | 重新连接尝试之间的延迟。 |
| `GODOT_PING_INTERVAL_MS` | `30000` | WebSocket ping 间隔。 |
| `GODOT_COMMAND_TIMEOUT_MS` | `30000` | 单个 Godot 命令的超时。 |
| `LOG_LEVEL` | `info` | `debug`、`info`、`warn` 或 `error` 之一。 |
示例：
```json
{
"mcpServers": {
"godot": {
"command": "node",
"args": ["/绝对路径/到/godot-mcp/server/dist/index.js"],
"env": {
"LOG_LEVEL": "debug",
"GODOT_COMMAND_TIMEOUT_MS": "60000"
}
}
}
}
```
## 开发
```bash
npm run setup
npm run verify
npm run start
```
有用命令：
| 命令 | 描述 |
| --- | --- |
| `npm run setup` | 安装服务器依赖项并构建 TypeScript。 |
| `npm run build` | 构建 MCP 服务器。 |
| `npm run verify` | 运行当前的验证套件。 |
| `npm run start` | 在 stdio 上启动已构建的 MCP 服务器。 |
| `npm run clean` | 删除生成的服务器构建输出和依赖项。 |
不要提交 `server/node_modules` 或 `server/dist`；它们是本地生成的。
## 仓库布局
```text
addons/godot_mcp/ Godot 编辑器插件
server/src/ TypeScript MCP 服务器
skills/ Godot 开发参考模块
examples/ 开源示例注册表
```
## 安全注意事项
插件可以读取和写入连接的 Godot 项目中的文件，并可以调用编辑器 API。仅在您信任的项目和 MCP 客户端中启用它。
## 许可证
MIT
