内容
# Godot MCP 服务器
[](https://github.com/sterion66/godot-mcp-server/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](LICENSE)
用于 Godot 4.x 游戏开发的全面 FastMCP 服务器。提供 AI 辅助工作流的工具：项目管理、文件操作、资产发现、GDScript 开发和可选的 Godot 执行。
<!-- mcp-name: io.github.sterion66/godot -->
[贡献](CONTRIBUTING.md) · [安全](SECURITY.md)
**安全模型：** 所有 Godot 项目、文件写入和资产库下载都限制在您机器上的单个 **工作区目录** （默认 `~/godot-games`）。服务器拒绝该树之外的路径。参见 [工作区设置](#工作区设置-必填)。
**代码执行：** `godot_run_game` 和 `godot_execute_script` 需要在服务器环境中设置 `GODOT_MCP_ALLOW_GODOT_EXEC`。**已发布的 MCP JSON 配置** 将其设置为 **`1`**，因此这些工具在复制和粘贴后有效。运行 `python godot_mcp_server.py` **不设置** 环境变量，执行仍然 **关闭**，直到您导出它。要锁定 IDE 安装，请删除变量或将其设置为 `0`。参见 [Godot 执行（环境）](#godot-执行-环境)。
**HTTP 传输：** 绑定到 `0.0.0.0` 或 `::` 会将 MCP 服务器暴露在所有网络接口上；如果您使用防火墙或 VPN，请优先使用 `127.0.0.1`。
**符号链接：** `GODOT_MCP_ROOT` 解析时会跟随符号链接；请将其指向您控制的真实目录。
## 功能
### 项目管理
- 自动检测 Godot 项目（`project.godot`）；列出工作区下的所有项目（`godot_list_projects`）
- 在工作区下创建新项目（`godot_create_project`）
- 解析项目设置和配置；列出自动加载和编辑器插件状态（只读插件）
- 在更改后刷新项目缓存
### 文件操作
- 读取/写入场景（`.tscn`）、脚本（`.gd`）、资源（`.tres`）
- 从模板创建新脚本、场景、资源
- 编辑现有文件并替换内容
- 验证场景和脚本语法
### 代码生成
- CharacterBody2D/3D 移动控制器
- 状态机模式
- 自定义资源
- 带有信号/导出的节点脚本
### 资产管理
- 按扩展名、模式、通配符发现资产
- 查找未使用的资产
- 使用正则表达式搜索文件内容
- **从 Godot 资产库搜索和下载**
- **浏览 GitHub 上的 Godot 仓库**
### 运行时集成
- 查找 Godot 可执行文件
- 检查 Godot 版本
- 无头运行游戏
- 执行 GDScript 代码
- 读取 Godot 日志
- 文件监视器配置
## 安装
```bash
# 从 PyPI 样式的可编辑安装（推荐给贡献者）
pip install -e .
# 或仅最小依赖
pip install -r requirements.txt
```
控制台入口点（在 `pip install -e .` 之后）：`godot-mcp-server`（与 `python godot_mcp_server.py` 相同）。
## 工作区设置（必填）
MCP 服务器 **仅** 在一个根文件夹下操作 Godot 项目。这可以防止助手读取或写入系统上的任意路径。
1. **创建默认文件夹** （每台机器一次）：
```bash
mkdir -p ~/godot-games
```
2. **将所有 Godot 游戏放在此处** — 每个游戏都是其自己的子目录，包含 `project.godot`，例如：
```text
~/godot-games/
my-platformer/ ← 在编辑器中打开此文件夹
project.godot
...
another-game/
project.godot
```
3. **在 `~/godot-games/.../your-game` 内打开您的 IDE 工作区** （或 `~/godot-games` 下的父文件夹），以便 MCP 进程可以从当前工作目录发现 `project.godot`。
4. **自定义位置：** 在启动服务器之前设置绝对路径：
```bash
export GODOT_MCP_ROOT="/path/to/your/godot-games"
python godot_mcp_server.py
```
在 Cursor / Claude / 其他 MCP 配置中，添加 `env`：
```json
"env": {
"GODOT_MCP_ROOT": "/path/to/your/godot-games"
}
```
如果未设置，默认值为 **`$HOME/godot-games`**。如果不存在，服务器会在启动时创建该目录。
5. **运行时检查：** 调用工具 `godot_get_workspace` 或读取资源 `project://workspace` 以查看活动工作区路径。
如果工具报告未找到项目，则您的 cwd 可能在工作区之外，或者 `project_path` 指向 `GODOT_MCP_ROOT` 之外。
## Godot 执行（环境）
运行游戏或执行 GDScript **以您的用户身份运行代码** （与从终端启动 Godot 相同）。服务器仅在 **`GODOT_MCP_ALLOW_GODOT_EXEC`** 设置为接受的“开启”值时启用 `godot_run_game` / `godot_execute_script`。
**已发布的配置（默认是的）：** 本仓库中的每个示例 JSON（`mcp_config.json`、`mcp_config.cursor.json` 等）都包含：
```json
"env": {
"GODOT_MCP_ALLOW_GODOT_EXEC": "1"
}
```
因此，如果您复制其中一个到您的 IDE，则执行 **允许** 无需额外步骤。 将其他键（例如 `GODOT_MCP_ROOT`）合并到同一个 `env` 对象中。
**CLI 无 MCP 配置：** 运行 `python godot_mcp_server.py` **不设置** 此变量；执行工具 **阻止** 直到您 `export GODOT_MCP_ALLOW_GODOT_EXEC=1` （或使用包装脚本）。
**更严格的设置：** 从 `env` 中删除 `GODOT_MCP_ALLOW_GODOT_EXEC`，或将其设置为 `0` / `false` / `no` / `off`，然后重启 MCP 客户端。
接受的“开启”值：`1`、`true`、`yes`、`on` （不区分大小写）。调用 `godot_get_workspace` 并检查 `godot_exec_allowed` 以确认。
## 用法
### CLI（stdio - 适用于 Claude Code/Cursor）
```bash
python godot_mcp_server.py
```
### HTTP 服务器
```bash
python godot_mcp_server.py --transport http --port 8765
```
## 配置
在 MCP 服务器的 `env` 中设置 `GODOT_MCP_ROOT`，如果您不使用默认的 `~/godot-games`。参见 [工作区设置](#工作区设置-必填)。已发布的代码片段包含 `GODOT_MCP_ALLOW_GODOT_EXEC`；参见 [Godot 执行（环境）](#godot-执行-环境)。
**服务器路径：** 示例使用 `"args": ["godot_mcp_server.py"]`，假设 MCP 进程在其 **工作目录** 中运行，该目录包含脚本（例如，您克隆了此仓库）。如果服务器无法启动，请将其替换为 **绝对路径** 到您机器上的 `godot_mcp_server.py`。
### 在您的编辑器中安装
展开一个部分并将 JSON 粘贴到您的工具期望的文件中。相同的 `godot` 服务器块在此仓库中作为 `mcp_config.*.json` 以供复制和粘贴。
<details>
<summary><strong>Cursor</strong></summary>
**macOS / Linux（项目或用户配置）** — 设置 → MCP → *添加新的全局 MCP 服务器* **或** 在项目根目录中创建 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"godot": {
"command": "python3",
"args": ["godot_mcp_server.py"],
"env": {
"GODOT_MCP_ALLOW_GODOT_EXEC": "1"
}
}
}
}
```
**Windows** — 如果 `python` 不在 MCP 主机的 PATH 上，请使用启动器或 `python.exe` 的绝对路径，并优先使用 `args` 中的 **绝对路径**：
```json
{
"mcpServers": {
"godot": {
"command": "cmd",
"args": ["/c", "python", "C:\\path\\to\\godot-mcp-server\\godot_mcp_server.py"],
"env": {
"GODOT_MCP_ALLOW_GODOT_EXEC": "1"
}
}
}
}
```
如果您不使用 `~/godot-games`，请将 `GODOT_MCP_ROOT` 合并到 `env` 中（参见 [工作区设置](#工作区设置-必填)）。
</details>
<details>
<summary><strong>Visual Studio Code</strong></summary>
使用 VS Code 构建提供的 MCP / 代理设置（通常是 **设置 → MCP** 或项目 `.vscode/mcp.json`，取决于版本和扩展）。粘贴与 Cursor 相同的结构：
```json
{
"mcpServers": {
"godot": {
"command": "python3",
"args": ["godot_mcp_server.py"],
"env": {
"GODOT_MCP_ALLOW_GODOT_EXEC": "1"
}
}
}
}
```
如果工作区文件夹不是仓库根目录，请在 `args` 中使用绝对路径。
</details>
<details>
<summary><strong>Claude Desktop</strong></summary>
编辑应用程序配置文件：
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"godot": {
"command": "python3",
"args": ["/absolute/path/to/godot_mcp_server.py"],
"env": {
"GODOT_MCP_ALLOW_GODOT_EXEC": "1"
}
}
}
}
```
重启 Claude Desktop 后保存。
</details>
<details>
<summary><strong>Claude Code</strong>（CLI）</summary>
合并到 `~/.claude/settings.json`（或使用 `claude mcp add` 如果您的 CLI 支持它 — 检查 `claude mcp --help`）：
```json
{
"mcpServers": {
"godot": {
"command": "python3",
"args": ["godot_mcp_server.py"],
"env": {
"GODOT_MCP_ALLOW_GODOT_EXEC": "1"
},
"description": "Godot 4.x 游戏开发服务器"
}
}
}
```
</details>
<details>
<summary><strong>Windsurf</strong>（Codeium）</summary>
**macOS / Linux:** 编辑 `~/.codeium/windsurf/mcp_config.json`，或使用 **CMD+SHIFT+P → “Windsurf: Configure MCP Servers”**。
```json
{
"mcpServers": {
"godot": {
"command": "python3",
"args": ["godot_mcp_server.py"],
"env": {
"GODOT_MCP_ALLOW_GODOT_EXEC": "1"
},
"description": "Godot 4.x 游戏开发 - 项目、场景、脚本、资产、运行时"
}
}
}
```
</details>
<details>
<summary><strong>Roo Code</strong></summary>
将以下内容粘贴到 Roo 的 MCP 设置（项目或全局）中，JSON 结构与上述相同。仓库复制：`roo_code_mcp.json`。
```json
{
"mcpServers": {
"godot": {
"command": "python3",
"args": ["godot_mcp_server.py"],
"env": {
"GODOT_MCP_ALLOW_GODOT_EXEC": "1"
},
"description": "Godot 4.x 游戏开发 - 项目、场景、脚本、资产、运行时"
}
}
}
```
</details>
<details>
<summary><strong>通用 JSON</strong>（任何 MCP 主机）</summary>
最小 stdio 配置 — 与此仓库中的 `mcp_config.json` 相同：
```json
{
"mcpServers": {
"godot": {
"command": "python3",
"args": ["godot_mcp_server.py"],
"env": {
"GODOT_MCP_ALLOW_GODOT_EXEC": "1"
},
"description": "Godot 4.x 游戏开发服务器 - 文件操作、资产管理、运行时集成"
}
}
}
```
</details>
### 限制（DoS / 滥用）
- **正则表达式搜索（`godot_search_content`）：** 模式长度上限；匹配列表上限；跳过大于 2 MiB 的文件。恶意正则表达式仍然可能很昂贵 — 保持模式简单。
- **资产 zip 下载：** 在提取前强制执行最大下载大小、每个文件解压大小、总解压大小和文件数量（参见 `godot_mcp_server.py` 顶部的常量）。
- **资产库 ID：** `godot_get_asset_info` / `godot_download_asset` 的 `asset_id` 必须仅为数字。
### HTTP 模式（远程）
除非您知道自己在做什么，否则请使用环回：
```bash
python godot_mcp_server.py --transport http --host 127.0.0.1 --port 8765
```
绑定到所有接口（`--host 0.0.0.0`）会记录警告并将 MCP 暴露给您的局域网 **没有身份验证** 在此服务器中。
然后使用 `serverUrl` 代替 `command`:
```json
{
"mcpServers": {
"godot": {
"serverUrl": "http://localhost:8765/mcp"
}
}
}
```
<details>
<summary><strong>为什么不重复 HTTP + stdio？</strong></summary>
仅运行 **一个** 传输到同一个项目（stdio **或** HTTP），不要同时运行两者，以避免冲突的 MCP 会话。
</details>
## 工具参考
`godot_mcp_server.py` 中注册了 40 种 MCP 工具（搜索 `@mcp.tool`）。摘要：
| 工具 | 描述 |
|------|-------------|
| `godot_get_workspace` | 显示 MCP 沙盒目录（`GODOT_MCP_ROOT`） |
| `godot_find_project` | 定位项目根目录（向上遍历或工作区扫描） |
| `godot_list_projects` | 列出工作区下的所有 `project.godot` |
| `godot_create_project` | 在工作区下创建 `project.godot` + 启动场景 |
| `godot_get_project_info` | 获取项目详细信息 |
| `godot_get_project_settings` | 解析 project.godot（包括只读 `editor_plugins_enabled`） |
| `godot_get_project_files` | 列出所有项目文件 |
| `godot_refresh_project` | 重新扫描场景/脚本/资源计数 |
| `godot_list_scenes` | 列出 `.tscn` 文件 |
| `godot_list_scripts` | 列出 `.gd` 文件 |
| `godot_list_resources` | 列出 `.tres` 文件 |
| `godot_list_autoload` | 列出自动加载单例 |
| `godot_list_editor_plugins` | 已安装的插件与 project.godot 中启用的插件（在 Godot 编辑器中启用插件） |
| `godot_find_assets` | 按扩展名查找 |
| `godot_find_unused_files` | 查找未引用的资产 |
| `godot_find_by_pattern` | 通配符模式搜索 |
| `godot_search_content` | 文件中的正则表达式搜索 |
| `godot_create_script` | 创建新的 GDScript |
| `godot_create_scene` | 创建新的场景 |
| `godot_create_resource` | 创建新的资源 |
| `godot_create_code_template` | 模板脚本 |
| `godot_read_scene` | 解析场景文件 |
| `godot_read_script` | 解析 GDScript |
| `godot_validate_scene` | 验证场景 |
| `godot_validate_script` | 验证语法 |
| `godot_edit_file` | 替换内容 |
| `godot_write_file` | 写入文件 |
| `godot_get_file_info` | 文件元数据 |
| `godot_find_godot_executable` | 定位 Godot |
| `godot_check_version` | Godot 版本 |
| `godot_run_game` | 无头运行 |
| `godot_execute_script` | 运行 GDScript |
| `godot_get_log` | 读取日志 |
| `godot_watch_files` | 配置监视器 |
| `godot_get_node_info` | 节点类型提示 |
| `godot_generate_uid` | 生成 UID |
| `godot_search_assetlib` | 搜索资产库 |
| `godot_get_asset_info` | 资产详情 |
| `godot_download_asset` | 下载/提取资产（促进嵌套 `addons/`） |
| `godot_browse_github` | 搜索 GitHub |
**编辑器插件：** 此服务器不会在 `project.godot` 中写入 `[editor_plugins]`（避免与打开的编辑器冲突）。通过上述工具安装插件；用户在 **项目设置 → 插件** 中启用插件；使用 `godot_list_editor_plugins` 验证。
## 资源
| 资源 | URI | 描述 |
|----------|-----|-------------|
| 项目信息 | `project://info` | 基本项目信息 |
| 项目概览 | `project://overview` | 文件计数 |
| 工作区 | `project://workspace` | MCP 沙盒路径（`GODOT_MCP_ROOT`） |
| 运行时 | `project://runtime` | Godot 版本 + 工作区路径 |
## 示例
### 创建一个平台游戏玩家
```python
# 使用模板
create_code_template("character_body_2d", "Player")
```
### 查找资产
```python
# 所有 PNG 文件
find_assets([".png", ".jpg"])
# 未使用的资产
find_unused_files()
```
### 搜索资产库
```python
search_assetlib("platformer")
# => [{title: "PlatformerController2D", ...}]
get_asset_info("1062")
# => {title, author, description, license, download_url}
```
### 无头运行游戏
需要已发布的 MCP JSON 配置文件中的 `GODOT_MCP_ALLOW_GODOT_EXEC`（已包含）。
```python
run_game(headless=True, quit_after_seconds=30)
```
## 要求
- Python 3.10+
- 依赖：`fastmcp`、`urllib3`（参见 `pyproject.toml`）
## 开发
```bash
pip install -e ".[dev]"
ruff check godot_mcp_server.py tests
pytest
```
持续集成在 **Python 3.10–3.14** 上运行（参见 `.github/workflows/ci.yml`）。 [Dependabot](.github/dependabot.yml) 每周为 pip 和 GitHub Actions 打开 PR。
可选：`pip install pre-commit && pre-commit install` 使用 `.pre-commit-config.yaml`。
## 发布到 GitHub
1. 在 GitHub 上创建一个空仓库（如果您已经在本地拥有 README/许可证，则不创建），例如 `godot-mcp-server`。
2. 添加远程仓库并推送：
```bash
cd /path/to/godot-mcp-server
git remote add origin https://github.com/YOUR_USER/godot-mcp-server.git
git push -u origin main
```
或使用 [GitHub CLI](https://cli.github.com/)：`gh repo create godot-mcp-server --public --source=. --remote=origin --push`
第一次推送后，CI 在每次推送和 PR 上运行。在 README 徽标 URL 中替换 `sterion66`，如果您使用不同的帐户或组织。
## 许可证
[MIT](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器