# Godot MCP

[![Github-sponsors](https://img.shields.io/badge/sponsor-30363D?style=for-the-badge&logo=GitHub-Sponsors&logoColor=#EA4AAA)](https://github.com/sponsors/Coding-Solo)

[![](https://badge.mcpx.dev?type=server 'MCP Server')](https://modelcontextprotocol.io/introduction)
[![Made with Godot](https://img.shields.io/badge/Made%20with-Godot-478CBF?style=flat&logo=godot%20engine&logoColor=white)](https://godotengine.org)
[![](https://img.shields.io/badge/Python-3.10%2B-blue?style=flat&logo=python&logoColor=white)](https://www.python.org/)
[![](https://img.shields.io/badge/vim-0A0197A?style=flat&logo=vim&logoColor=white)](https://www.vim.org/)

[![](https://img.shields.io/github/last-commit/Coding-Solo/godot-mcp 'Last Commit')](https://github.com/Coding-Solo/godot-mcp/commits/main)
[![](https://img.shields.io/github/stars/Coding-Solo/godot-mcp 'Stars')](https://github.com/Coding-Solo/godot-mcp/stargazers)
[![](https://img.shields.io/github/forks/Coding-Solo/godot-mcp 'Forks')](https://github.com/Coding-Solo/godot-mcp/network/members)
[![](https://img.shields.io/badge/License-MIT-red.svg 'MIT License')](https://opensource.org/licenses/MIT)

[![English](https://img.shields.io/badge/文档-English-blue.svg)](README.md)

一个用于与 Godot 游戏引擎交互的模型上下文协议（MCP）服务器。

## 简介

Godot MCP 使 AI 助手能够通过标准化接口启动 Godot 编辑器、运行项目、捕获调试输出并控制项目执行。

这种直接的反馈循环帮助像 Claude 这样的 AI 助手理解在实际 Godot 项目中什么有效、什么无效，从而改进代码生成和调试辅助。

## 功能

- **启动 Godot 编辑器**：为特定项目打开 Godot 编辑器
- **运行 Godot 项目**：在调试模式下执行 Godot 项目
- **捕获调试输出**：检索控制台输出和错误消息
- **控制执行**：编程方式启动和停止 Godot 项目
- **获取 Godot 版本**：检索已安装的 Godot 版本
- **列出 Godot 项目**：在指定目录中查找 Godot 项目
- **项目分析**：获取项目结构的详细信息
- **场景管理**：
  - 使用指定的根节点类型创建新场景
  - 使用可自定义属性向现有场景添加节点
  - 向 Sprite2D 节点加载精灵和纹理
  - 导出 3D 场景为 GridMap 使用的 MeshLibrary 资源
  - 使用创建变体的选项保存场景
- **UID 管理**（适用于 Godot 4.4+）：
  - 获取特定文件的 UID
  - 通过重新保存资源来更新 UID 引用

## 要求

- 系统上已安装 [Godot Engine](https://godotengine.org/download)
- [Python](https://www.python.org/downloads/) >= 3.10
- [uv](https://docs.astral.sh/uv/) 包管理器（包含 `uvx` 工具，无需额外安装）
- 支持 MCP 的 AI 助手（Cline、Cursor 等）

> **什么是 uvx？**
>
> `uvx` 是 uv 包管理器附带的工具，可以直接从 GitHub 运行 Python 应用程序，而无需克隆仓库或手动管理虚拟环境。当你安装了 uv 后，`uvx` 命令就自动可用。
>
> **使用 uvx 的优势：**
> - 无需克隆仓库
> - 自动管理依赖项和虚拟环境
> - 总是运行最新版本
> - 简化配置过程

## 安装

### 前置条件

1. 安装 Python 3.10 或更高版本
2. 安装 uv 包管理器（包含 `uvx` 工具，无需额外安装）：
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```
   或按照 [uv 安装指南](https://docs.astral.sh/uv/getting-started/installation) 操作
   >
   > 安装完成后，你可以运行 `uv --version` 和 `uvx --version` 来确认安装成功。

### 步骤 1：运行服务器

#### 推荐：使用 uvx（无需克隆）

**推荐方法** - 使用 `uvx` 直接从 GitHub 运行，无需克隆：

```bash
uvx --from "git+https://github.com/ChanceFlow/godot-mcp@main" godot-mcp
```

#### 备选：本地开发（用于贡献）

仅当你计划贡献或本地开发时才克隆仓库：

```bash
git clone https://github.com/ChanceFlow/godot-mcp.git
cd godot-mcp
uv sync
uv run python godot_mcp/server.py
```

### 步骤 2：使用 AI 助手配置

#### 推荐：使用 uvx

将以下内容添加到你的 AI 助手的 MCP 设置中（推荐大多数用户使用）：

**对于 Cline**（`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`）：

```json
{
  "mcpServers": {
    "godot": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ChanceFlow/godot-mcp@main", "godot-mcp"],
      "env": {
        "DEBUG": "true"
      },
      "disabled": false,
      "autoApprove": [
        "launch_editor",
        "run_project",
        "get_debug_output",
        "stop_project",
        "get_godot_version",
        "list_projects",
        "get_project_info",
        "create_scene",
        "add_node",
        "load_sprite",
        "export_mesh_library",
        "save_scene",
        "get_uid",
        "update_project_uids"
      ]
    }
  }
}
```

**对于 Cursor UI：**

1. 前往 **Cursor 设置** > **功能** > **MCP**
2. 点击 **+ 添加新的 MCP 服务器** 按钮
3. 填写表单：
   - 名称：`godot`（或你喜欢的任何名称）
   - 类型：`command`
   - 命令：`uvx --from "git+https://github.com/ChanceFlow/godot-mcp@main" godot-mcp`
4. 点击 "添加"
5. 你可能需要在 MCP 服务器卡片的右上角点击刷新按钮来填充工具列表

**对于 Cursor（项目特定）：**

在你的项目目录中创建一个文件 `.cursor/mcp.json`，内容如下：

```json
{
  "mcpServers": {
    "godot": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ChanceFlow/godot-mcp@main", "godot-mcp"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}
```

#### 备选：本地开发（用于贡献）

仅当你已在本地克隆了仓库时才使用：

**对于 Cline：**

```json
{
  "mcpServers": {
    "godot": {
      "command": "uv",
      "args": ["run", "python", "godot_mcp/server.py"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}
```

**对于 Cursor：** 使用 `uv run python godot_mcp/server.py` 作为命令。

### 步骤 3：可选环境变量

你可以使用这些环境变量自定义服务器行为：

- `GODOT_PATH`：Godot 可执行文件的路径（覆盖自动检测）
- `DEBUG`：设置为 "true" 以启用详细的服务器端调试日志

## 示例提示

一旦配置完成，你的 AI 助手将根据需要自动运行 MCP 服务器。你可以使用以下提示：

```text
"为 /path/to/project 的项目启动 Godot 编辑器"

"运行我的 Godot 项目并显示任何错误"

"获取我的 Godot 项目结构的信息"

"帮助我调试这个 Godot 项目中的错误：[粘贴错误]"

"为具有双跳跃和墙滑动的角色控制器编写 GDScript"

"在我的 Godot 项目中创建一个带有 Player 节点的新场景"

"向我的玩家场景添加一个 Sprite2D 节点并加载角色纹理"

"将我的 3D 模型导出为 GridMap 使用的 MeshLibrary"

"为游戏的主菜单创建一个带有按钮和标签的 UI 场景"

"获取我的 Godot 4.4 项目中特定脚本文件的 UID"

"升级到 4.4 后更新我的 Godot 项目中的 UID 引用"
```

## 实现细节

### 架构

Godot MCP 服务器使用捆绑的 GDScript 方法来处理复杂操作：

1. **直接命令**：简单的操作（如启动编辑器或获取项目信息）直接使用 Godot 的内置 CLI 命令。
2. **捆绑操作脚本**：复杂的操作（如创建场景或添加节点）使用一个单一的、全面的 GDScript 文件（`godot_operations.gd`）来处理所有操作。

这种架构提供了几个好处：

- **无临时文件**：消除了对临时脚本文件的需求，保持系统整洁
- **简化的代码库**：将所有 Godot 操作集中在一个（某种程度上）有组织的文件中
- **更好的可维护性**：使添加新操作或修改现有操作变得更容易
- **改进的错误处理**：在所有操作中提供一致的错误报告
- **减少开销**：最小化文件 I/O 操作以获得更好的性能

捆绑脚本接受 JSON 格式的操作类型和参数，允许灵活和动态的操作执行，而无需为每个操作生成临时文件。

## 开发

### 运行服务器

直接执行：
```bash
uv run python godot_mcp/server.py
```

使用 MCP Inspector 开发模式：
```bash
uv run mcp dev godot_mcp/server.py
```

### 测试

使用 pytest 运行测试：
```bash
pytest
```

## 故障排除

- **未找到 Godot**：将 GODOT_PATH 环境变量设置为你的 Godot 可执行文件
- **连接问题**：确保服务器正在运行并重启你的 AI 助手
- **无效的项目路径**：确保路径指向包含 project.godot 文件的目录
- **Python 版本**：确保你使用的是 Python 3.10 或更高版本

## 许可证

本项目采用 MIT 许可证 - 详情请参阅 [LICENSE](LICENSE) 文件。