内容
-mcp
**English** | [中文](README_CN.md)
[](https://modelcontextprotocol.io/introduction)
[](https://godotengine.org)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
一款适用于Godot游戏引擎的[模型上下文协议](https://modelcontextprotocol.io/introduction)服务器。 **156种工具**，涵盖运行时交互、后台场景操作、项目管理、3D/2D渲染、UI控件、音频、动画、物理、网络和C#评估。
从 [Coding-Solo/godot-mcp](https://github.com/Coding-Solo/godot-mcp)（通过 [tugcantopaloglu/godot-mcp](https://github.com/tugcantopaloglu/godot-mcp)） fork而来，现独立维护，专注于C# Godot项目。
## 功能
### 运行时交互（game_* 工具）
- **代码执行**：`game_eval`（GDScript），`game_eval_csharp` + `game_eval_csharp_snapshot`（C# via EvalGateway）
- **节点检查**：`game_get_property`，`game_set_property`，`game_call_method`，`game_get_node_info`，`game_get_scene_tree`
- **输入注入**：`game_click`，`game_key_press`，`game_key_hold`，`game_mouse_drag`，`game_touch`，`game_gamepad`
- **信号**：`game_connect_signal`，`game_emit_signal`，`game_await_signal`
- **动画**：`game_play_animation`，`game_tween_property`，`game_animation_tree`，`game_create_animation`
- **调试**：`game_get_logs`，`game_get_errors`，`game_performance`，`game_screenshot`，`game_pause`
- **3D/2D**：灯光、网格、CSG、粒子、画布、物理、射线检测、导航、瓷砖地图
- **UI**：文本控件、弹出窗口、树、菜单、选项卡、范围、主题
- **音频**：播放、总线控制、效果、空间音频
- **网络**：HTTP、WebSocket、ENet多人游戏、RPC
- **系统**：窗口、操作系统信息、时间缩放、本地化、视口
### 后台操作（无需运行游戏）
- **场景I/O**：`read_scene`，`modify_scene_node`，`remove_scene_node`，`create_scene`，`add_node`，`save_scene`
- **项目**：`read_project_settings`，`modify_project_settings`，`manage_autoloads`，`manage_input_map`，`manage_export_presets`
- **文件**：`read_file`，`write_file`，`delete_file`，``，`list`
- **资源**：`create，`manage，`manage_shader`，`manage_theme_resource`
-**：`create_script`，`attach_script`，_scene_signals`
### 评估（game_eval）
对于C# Godot项目，`game_eval_csharp` 和 `game_eval_csharp目标项目的 `Eval 自动加载来评估C表达式并获取结构化解决了GDScript `game 的限制，即C、纯C#类/Minion/Board）、>` 和枚举不可需要下游项目实现具有 path)` 和 `GetSnapshot(string kind)` 方法的Gateway` 自动加载。
## 要求
- [Godot Engine](https://godot/download) 4.x（4.4+ for UID 功能）
- [Node.js](https://nodejs.org/) >= 18.0.0
- 一个与MCP兼容的AI助手（Claude Code、Cline、Cursor、OpenCode等）
## 安装
```bash
git clone https://github.com/WhiteGiverMa/godot-mcpcd godot
npm install
npm run build
配置
### Claude Code / OpenCode
```json "mcpServers": "godot-mcp": {
"command": "node",
"args": ["/absolute/path/to/godot/build/index.js"],
"environment": {
"G_PATH": "/path/to",
"GOD_PATH": "/path/to/godot/project"
}
}
}
```
### Cline（VS Code） `cline_mcp_settings：
```json
"mcpServers": "godot-mcp": {
"command": " "args": [/path/to/godot-mcp/build/index.js"]
}
}
}
```
### Cursor `.cursor/mcp.json`：
```json
{
"mcpServers": {
"godot-mcp": "command": "node",
"args": ["/absolute/path/to/godot-mcp/build/index.js"]
}
}
}
```
## 运行时工具设置
要使用 `game_*` 运行时工具，您的Godot项目需要MCP交互服务器：
1. 将 `build/scripts/mcp_interaction_server.gd` 复制到您的项目中
2. 在Godot中：**项目 > > 自动加载**
3. 添加脚本，自动加载 `McpInteractionServer `127.01:9090在游戏运行时接受JSON命令。
### C# 评估设置
对于_eval_csharp` / `game_eval_csharp_snapshot`C# Godot项目Gateway` 自动公开：
- `Variant Eval(string pathExpr)` — #路径表达式
- `Variant GetSnapshot(string kind)` — 返回结构化快照（战斗/玩家/敌人/棋盘）
参见 [odyssey-cards/Scripts/Infrastructure/EvalGateway.cs](https://github.com/WhiteGiverMa/odyssey-cards/blob/dev/Scripts/Infrastructure/EvalGateway.cs) 获取参考实现。
## 环境变量
| 变量 | 描述 |
|----------|-------------|
| `GODOT_PATH` | Godot可执行文件的路径（覆盖自动检测） |
| `GODOT_PROJECT_PATH` |项目路径 |
|` | 设置为 `"true进行详细的服务器端日志记录 |
## 架构通信通道：
1. **后台CLI** — 无需运行游戏的场景/资源/项目操作。运行 `godot --headless --script godot_operations.gd <op> <json>`。
2. **TCP套接字** — 与正在运行的游戏进行运行时交互。`mcp_interaction_server.gd` 自动加载监听端口9090，处理来自TypeScript MCP服务器的JSON命令。
### 源代码布局
| 路径 | 描述 |
|------|-------------|
| `src/index.ts` |，156种工具定义，156种处理程序 |
| `src/utils.ts` | 纯实用函数（参数映射，验证） |
| `src/scripts/mcp_interaction_server.gd` | 运行时TCP交互服务器自动加载 |
| `src/scripts/godot_operations.gd` | 后台GDScript操作运行程序 |
| `tests/` | Vitest测试套件（426个测试） |
## 测试
```bash
npm test # 运行一次
npm run test:watch # 监视模式
```
| 文件 | 测试 | 覆盖率 |
|------|-------|----------|
| `tests/utils.test.ts` | 31 | 参数映射，路径验证，错误响应 |
| `tests/tool-definitions.test.ts` | 159 | 所有156种工具已定义，模式有效，描述 ≤ 80字符 |
| `tests/handlers.test.ts` | 236 | 处理程序参数转换，必需参数验证，切换完整性 |
## 开发
```bash
npm run build # tsc + 复制GDScript到build/scripts
npm run watch # tsc --watch
npm run inspector # MCP检查器调试
```
### 下游同步
`scripts/sync-downstream.ps1` 将 `build/scripts/*.gd` 复制到下游Godot项目：
```powershell
./scripts/sync-downstream.ps1 # 构建 + 同步
./scripts/sync-downstream.ps1 -SkipBuild # 仅同步
```
## 示例提示
```text
"运行我的Godot项目并检查错误"
"获取正在运行的游戏中的玩家位置"
"将玩家生命值设为100"
"读取test_level.tscn场景并显示节点树"
"评估此C#路径：CombatManager.PlayerHero.CurrentHealth"
"从正在运行的C#游戏中获取战斗快照"
"将敌人的'died'信号连接到游戏管理器的'on_enemy_died'方法"
"将摄像机的位置缓动到（0，10，-5），持续2秒，缓动方式为ease-out"
"获取性能指标 - 我的FPS和绘制调用次数是多少？"
"暂停游戏并截图"
"创建一个名为'MyGame'的新Godot项目并编写玩家脚本"
```
## 致谢
- **原始项目**：[godot-mcp](https://github.com/Coding-Solo/godot-mcp) by Solomon Elias (Coding-Solo)
- **扩展fork**：[tugcantopaloglu/godot-mcp](https://github.com/tugcantopaloglu/godot-mcp) by Tugcan Topaloglu — 扩展到149种工具
- **当前维护者**：[WhiteGiverMa](https://github.com/WhiteGiverMa) — forked 2026-06，添加C#评估工具，为C# Godot项目垂直领域独立维护
## 许可证
MIT License — 请参阅 [LICENSE](LICENSE)。
版权所有 (c) 2026 马戈 (WhiteGiverMa)
