Godot MCP Server

一个为 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）

• 解析项目设置和配置；列出自动加载（autoload）和编辑器插件状态（插件为只读）

• 在更改后刷新项目缓存

文件操作

• 读写场景（.tscn）、脚本（.gd）、资源（.tres）

• 从模板创建新的脚本、场景、资源

• 通过内容替换编辑现有文件

• 验证场景和脚本语法

代码生成

• CharacterBody2D/3D 移动控制器

• 状态机模式

• 自定义资源

• 带信号/导出属性的节点脚本

资源管理

• 按扩展名、模式、glob 发现资源

• 查找未使用的资源

• 使用正则表达式搜索文件内容

• 从 Godot Asset Library 搜索并下载

• 浏览 GitHub 上的 Godot 仓库

运行时集成

• 查找 Godot 可执行文件

• 检查 Godot 版本

• 以无头模式运行游戏

• 执行 GDScript 代码

• 读取 Godot 日志

• 文件监视器配置

Related MCP server: Godot MCP

安装

# 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 以查看当前的工作区路径。

如果工具报告未找到项目，你的 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 等）都包含：

"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 服务器配置块，便于复制粘贴。

macOS / Linux（项目或用户配置） — 设置 → MCP → 添加新的全局 MCP 服务器 或在项目根目录创建 .cursor/mcp.json：

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

Windows — 如果 python 不在 MCP 主机的 PATH 中，请使用启动器或 python.exe 的完整路径，并且 args 中最好使用绝对路径：

{
  "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 中（请参阅工作区设置）。

使用你的 VS Code 版本提供的 MCP / agent 设置（通常是 设置 → MCP 或项目中的 .vscode/mcp.json，具体取决于版本和扩展）。粘贴与 Cursor 相同的结构：

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

如果工作区文件夹不是仓库根目录，请在 args 中使用绝对路径。

编辑应用配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows： %APPDATA%\Claude\claude_desktop_config.json

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

保存后重启 Claude Desktop。

合并到 ~/.claude/settings.json 中（或者如果你的 CLI 支持，可以使用 claude mcp add — 请查看 claude mcp --help）：

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

macOS / Linux： 编辑 ~/.codeium/windsurf/mcp_config.json，或使用 CMD+SHIFT+P → “Windsurf: Configure MCP Servers”。

{
  "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"
    }
  }
}

粘贴到 Roo 的 MCP 设置中（项目或全局），JSON 结构与上面相同。仓库副本：roo_code_mcp.json。

{
  "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"
    }
  }
}

最小的 stdio 配置 — 与本仓库中的 mcp_config.json 相同：

{
  "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 模式（远程）

除非你明确知道自己在做什么，否则请使用回环地址：

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"
    }
  }
}

对同一个项目，只运行一种传输（stdio 或 HTTP），不要同时运行两者，以避免冲突的 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/license，请勿添加），例如 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