内容
# Godot MCP 原生插件
[](https://godotengine.org)
[](LICENSE)
[](docs/changelog.md)
[](docs/tools/README.md)
> 中文文档见 [README.zh.md](README.zh.md)
**通过 AI 助手驱动 Godot。** Godot MCP 原生插件是一款编辑器插件，它在 Godot 内部运行一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，这样 Claude、Cursor、Cline 和 Codex 等 AI 客户端可以通过自然语言读取和编辑您的项目 — 场景、脚本、节点、资源，甚至是运行中的游戏。
无需 Node.js，无需 Python 桥接，无需外部服务器。协议使用 GDScript 实现，直接与引擎通信。
---
## 为什么使用这个插件
- **原生且无依赖** — MCP 服务器是编辑器进程的一部分；无需安装或运行其他组件。
- **两种传输方式** — HTTP/SSE（默认，端口 `9080`）适用于编辑器和远程客户端，stdio 适用于本地进程客户端。
- **206 种工具，合理分类** — 30 种高价值核心工具默认启用；174 种高级工具一键启用。
- **运行时感知** — 探针允许 AI 检查和操控运行中的游戏，而不仅仅是编辑时状态：实时场景树、表达式求值、输入注入、动画/音频/着色器/图块地图控制。
- **安全设计** — 可选的 Bearer-token 身份验证、路径验证和引擎 API 而不是调用操作系统命令。
## 安装
**资产库（推荐）**：在 Godot 中打开 **AssetLib**，搜索 **"Godot MCP 原生"**，然后 **下载 → 安装**。
**手动安装**：将 `addons/godot_mcp` 复制到您的项目的 `addons/` 文件夹中。
然后在 **项目 → 项目设置 → 插件** 中启用它。一个新的 **MCP** 控制台面板将出现。
➡️ 完整教程：[docs/getting-started.md](docs/getting-started.md)
## 30 秒连接
1. 在 **MCP** 面板中，选择 **HTTP** 并点击 **启动**（默认端口 `9080`）。
2. 将您的客户端指向 `http://localhost:9080/mcp`:
```json
{
"mcpServers": {
"godot-mcp": { "url": "http://localhost:9080/mcp" }
}
}
```
3. 询问您的助手： *"获取 Godot 项目信息。"* — 它调用 `get_project_info`，您已连接。
Claude Desktop、Cursor、Trae、Cline、OpenCode 和 Codex 的代码片段在 [入门](docs/getting-started.md#5-connect-an-ai-client) 和 [配置](docs/configuration.md#client-configuration) 中。
## AI 可以做什么
该插件公开了 **206 种工具**，分为六类（另外还有 2 种始终开启的元工具用于工具发现）。每个工具都链接到完整的工具参考。
| 类别 | 工具数量 | 涵盖内容 |
| --- | ---: | --- |
| [节点](docs/tools/node-tools.md) | 26 | 创建/编辑节点、信号、组、锚点、批量编辑、审计 |
| [脚本](docs/tools/script-tools.md) | 17 | 读取/写入/验证 GDScript 和 C#，搜索，符号索引 |
| [场景](docs/tools/scene-tools.md) | 12 | 创建/打开/保存场景，结构，预制实例化，图块地图 |
| [编辑器](docs/tools/editor-tools.md) | 23 | 运行/停止，截图，选择，检查器，导出，缓冲区同步 |
| [调试和运行时](docs/tools/debug-tools.md) | 71 | 日志，调试器，断点，性能分析器，运行时控制 |
| [项目](docs/tools/project-tools.md) | 55 | 设置，资源，输入映射，审计，4.7 迁移，资产生成，任务计划 |
| [元](docs/tools/README.md#meta-tools-tool-discovery) | 2 | 始终开启的工具发现和按需启用（`list_tool_catalog`，`enable_tools`） |
只有 30 种 **核心** 工具（另外还有 2 种始终开启的 **元** 工具）默认启用 — 您可以从 MCP 面板启用任意 174 种 **高级** 工具。参见 [工具参考](docs/tools/README.md)。
### 示例提示
```
在当前场景中添加一个 Camera2D 并使其跟随玩家。
创建一个包含 Play、Options 和 Quit 按钮的主菜单场景。
读取我的移动脚本并重构为使用状态机。
运行项目，然后告诉我实时的 FPS 和节点数量。
```
## 配置
在 MCP 面板中配置所有内容；设置将保存到 `user://mcp_settings.cfg`。
| 设置 | 默认值 | 设置 | 默认值 |
| --- | --- | --- | --- |
| `transport_mode` | `http` | `sse_enabled` | `true` |
| `http_port` | `9080` | `auto_start` | `false` |
| `auth_enabled` | `false` | `security_level` | `1` |
| `auth_token` | `""` | `rate_limit` | `1000` |
无头启动和 CLI 覆盖：
```bash
godot --editor --path /path/to/project -- --mcp-server --mcp-port=9080
```
➡️ 详情：[docs/configuration.md](docs/configuration.md)
## 要求
- Godot Engine 4.7（GL 兼容性渲染器）。
- 无运行时依赖。`npx` 仅适用于通过 `mcp-remote` 连接的客户端；Python 3.8+ 仅适用于运行集成测试。
## 文档
- [入门](docs/getting-started.md)
- [配置](docs/configuration.md)
- [架构](docs/architecture.md)
- [工具参考](docs/tools/README.md)
- [测试](docs/testing.md)
- [贡献](docs/contributing.md)
- [更新日志](docs/changelog.md)
## 贡献
欢迎提交问题和拉取请求。请阅读 [docs/contributing.md](docs/contributing.md) 以了解约定、工具创作工作流程和文档更新检查清单。
## 许可证
在 [MIT License](LICENSE) 下发布。
## 作者
**xianyu0514**
## 致谢
- Godot Engine 团队。
- 模型上下文协议规范和社区。
- Anthropic 的 Claude，它启发了此集成。
---
*社区插件 — 不官方 affiliated 与 Godot Engine 或 Anthropic。*
