godot

Godot MCP 服务端

面向 Godot 4.x 游戏开发的全面 FastMCP 服务端。为 AI 辅助工作流提供工具：项目管理、文件操作、资源发现、GDScript 开发，以及可选的 Godot 执行功能。

贡献指南 · 安全

安全模型： 所有 Godot 项目、文件写入和 Asset Library 下载都限制在你机器上的单个工作区目录内（默认为 ~/godot-games）。服务端会拒绝该目录树以外的路径。请参阅工作区设置。

代码执行： godot_run_game 和 godot_execute_script 需要在服务端环境中设置 GODOT_MCP_ALLOW_GODOT_EXEC。随附的 MCP JSON 配置将其设为 1，因此复制粘贴后即可使用这些工具。运行 python godot_mcp_server.py 而不设置该环境变量时，执行功能仍会保持关闭，除非你导出该变量。若要锁定 IDE 安装，请移除该变量或将其设为 0。请参阅 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 移动控制器
• 状态机模式
• 自定义资源
• 包含信号/导出变量的节点脚本

资源管理

• 按扩展名、模式和 glob 查找资源
• 查找未使用的资源
• 使用正则表达式搜索文件内容
• 搜索并从 Godot Asset Library 下载
• 浏览 GitHub 上的 Godot 仓库

运行时集成

• 查找 Godot 可执行文件
• 检查 Godot 版本
• 以无头模式运行游戏
• 执行 GDScript 代码
• 读取 Godot 日志
• 文件监视器配置

安装

# From PyPI-style editable install (recommended for contributors)
pip install -e .

# Or minimal deps only
pip install -r requirements.txt

（运行 pip install -e . 后）控制台入口为：godot-mcp-server（与 python godot_mcp_server.py 相同）。

工作区设置（必需）

MCP 服务仅对位于一个根文件夹下的 Godot 项目进行操作。这样可以防止助手读取或写入系统中的任意路径。

1. 创建默认文件夹（每台机器仅需一次）：

   mkdir -p ~/godot-games
   

2. 将每个 Godot 游戏都放在此处——每个游戏都应是包含 project.godot 的独立子目录，例如：

   ~/godot-games/
     my-platformer/     ← open this folder in your editor
       project.godot
       ...
     another-game/
       project.godot
   

3. 在 ~/godot-games/.../your-game（或 ~/godot-games 下的父文件夹）中打开 IDE 工作区，这样 MCP 进程就能从当前工作目录中发现 project.godot。

4. **自定义位置：**启动服务前设置绝对路径：

   export GODOT_MCP_ROOT="/path/to/your/godot-games"
   python godot_mcp_server.py
   

   在 Cursor / Claude / 其他 MCP 配置中，添加 env：

   "env": {
     "GODOT_MCP_ROOT": "/path/to/your/godot-games"
   }
   

   如果未设置，默认路径为 $HOME/godot-games。如果该目录不存在，服务会在启动时创建它。

5. **运行时检查：**调用工具 godot_get_workspace 或读取资源 project://workspace，查看当前工作区路径。

如果工具报告未找到项目，可能是当前工作目录不在工作区内，或者 project_path 指向了 GODOT_MCP_ROOT 之外的位置。

Godot 执行（环境）

运行游戏或执行 GDScript 会以你的用户身份运行代码（与从终端启动 Godot 相同）。只有在设置为可接受的“开启”值时，服务才会启用 godot_run_game / godot_execute_script。

**随附的配置（默认开启）：**本仓库中的每个示例 JSON（mcp_config.json、mcp_config.cursor.json 等）都包含：

"env": {
  "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
}

因此，如果你将其中一个配置复制到 IDE 中，无需其他步骤即可允许运行。将其他键（例如 GODOT_MCP_ROOT）合并到同一个 env 对象中。

未使用 MCP 配置的 CLI：运行 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）

python godot_mcp_server.py

HTTP 服务

python godot_mcp_server.py --transport http --port 8765

配置

如果不使用默认路径 ~/godot-games，请在 MCP 服务的 env 中设置 GODOT_MCP_ROOT。请参阅工作区设置。下方随附的配置片段包含 GODOT_MCP_ALLOW_GODOT_EXEC；请参阅 Godot 执行（环境）。

服务路径：示例使用 "args": ["godot_mcp_server.py"]，前提是 MCP 进程以包含该脚本的文件夹（例如，你克隆的本仓库）为工作目录运行。如果服务无法启动，请将其替换为你机器上 godot_mcp_server.py 的绝对路径。

在编辑器中安装

展开一个部分，并将 JSON 粘贴到工具要求的文件中。仓库中的 mcp_config.*.json 也包含相同的 godot 服务配置块，可直接复制粘贴。

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "cmd",
      "args": ["/c", "python", "C:\\path\\to\\godot-mcp-server\\godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["/absolute/path/to/godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development server"
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development - project, scenes, scripts, assets, runtime"
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game dev - project, scenes, scripts, assets, runtime"
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development server - file ops, asset management, runtime integration"
    }
  }
}

限制（DoS / 滥用）

• **正则表达式搜索（godot_search_content）：**模式长度和匹配列表均设有上限；大于 2 MiB 的文件将被跳过。恶意正则表达式仍可能造成高开销，请保持模式简单。
• **资源 zip 下载：**提取前会限制最大下载大小、单个文件的未压缩大小、总未压缩大小和文件数量（参见 godot_mcp_server.py 顶部附近的常量）。
• Asset Library ID：godot_get_asset_info / godot_download_asset 的 asset_id 必须仅包含数字。

HTTP 模式（远程）

除非你清楚自己在做什么，否则请使用 loopback：

python godot_mcp_server.py --transport http --host 127.0.0.1 --port 8765

绑定到所有接口（--host 0.0.0.0）会记录一条警告，并在此服务中不设任何身份验证地向局域网开放 MCP。

然后使用 serverUrl 替代 command：

{
  "mcpServers": {
    "godot": {
      "serverUrl": "http://localhost:8765/mcp"
    }
  }
}

godot_mcp_server.py 中注册了 40 个 MCP 工具（搜索 @mcp.tool）。概要：

**编辑器插件：**此服务不会写入 project.godot 中的 [editor_plugins]（以避免与已打开的编辑器冲突）。通过上述工具安装插件；用户在 Godot 的 项目设置 → 插件 中启用插件；使用 godot_list_editor_plugins 进行验证。

资源

示例

创建平台跳跃游戏玩家

# Using template
create_code_template("character_body_2d", "Player")

查找资源

# All PNG files
find_assets([".png", ".jpg"])

# Unused assets
find_unused_files()

搜索资源库

search_assetlib("platformer")
# => [{title: "PlatformerController2D", ...}]

get_asset_info("1062")
# => {title, author, description, license, download_url}

无头运行游戏

需要设置 GODOT_MCP_ALLOW_GODOT_EXEC（已包含在随附的 MCP JSON 配置中）。

run_game(headless=True, quit_after_seconds=30)

要求

• Python 3.10+
• 依赖项：fastmcp、urllib3（参见 pyproject.toml）

开发

pip install -e ".[dev]"
ruff check godot_mcp_server.py tests
pytest

持续集成在 Python 3.10–3.14 上运行（参见 .github/workflows/ci.yml）。Dependabot 每周为 pip 和 GitHub Actions 创建 PR。

可选：运行 pip install pre-commit && pre-commit install，使用 .pre-commit-config.yaml。

发布到 GitHub

1. 在 GitHub 上创建一个空仓库（如果本地已有 README／许可证，则不要添加），例如 godot-mcp-server。
2. 添加远程仓库并推送：

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：gh repo create godot-mcp-server --public --source=. --remote=origin --push

首次推送后，CI 会在每次推送和 PR 时运行。如果你使用其他账号或组织，请替换 README 徽章 URL 中的 sterion66。

许可证

MIT