Skip to main content
Glama
io.github.sterion66/godot

io.github.sterion66/godot

by sterion66

Godot MCP Server

CI Python 3.10+ License: MIT

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

安装

# 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)。摘要:

工具

描述

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

Glob 模式搜索

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 的 项目设置 → 插件 中启用插件;使用 godot_list_editor_plugins 进行验证。

资源

资源

URI

描述

项目信息

project://info

基本项目信息

项目概览

project://overview

文件数量

工作区

project://workspace

MCP 沙箱路径(GODOT_MCP_ROOT)

运行时

project://runtime

Godot 版本 + 工作区路径

示例

创建平台跳跃游戏玩家

# 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

Available Tools

40 tools
godot_browse_githubBrowse Godot GitHubB
Read-only

Search for Godot-related repositories on GitHub.

Inputs: query (required), sort, repo_type. Returns: object

godot_check_versionCheck Godot VersionB
Read-only

Check the Godot version.

Inputs: godot_path. Returns: object

godot_create_code_templateCreate Code TemplateB

Create code from a template.

Template types:

  • character_body_2d: CharacterBody2D script

  • character_body_3d: CharacterBody3D script

  • node: Basic node script

  • resource: Custom resource script

  • state_machine: State machine script

Inputs: name (required), template_type (required), project_path. Returns: result

godot_create_projectCreate Godot ProjectA

Create a Godot project under the MCP workspace: writes project.godot and a starter .tscn (what the Project Manager also creates on disk). When run_godot_import is true and GODOT_MCP_ALLOW_GODOT_EXEC=1, runs the Godot editor in headless import mode (--import) so the .godot/ cache folder exists and resources are processed—this is the engine's own initialization step; there is no separate "create project" binary in Godot.

Inputs: relative_path (required), godot_path, main_scene, display_name, +4 more. Returns: object

godot_create_resourceCreate ResourceC

Create a new resource file.

Inputs: resource_type (required), properties, project_path, resource_name. Returns: result

godot_create_sceneCreate SceneC

Create a new scene file.

Inputs: root_name (required), root_type (required), resources, child_nodes, +1 more. Returns: result

godot_create_scriptCreate GDScriptC

Create a new GDScript file.

Inputs: class_name (required), exports, extends, signals, +3 more. Returns: result

godot_download_assetDownload AssetA

Download an asset from the Asset Library.

Zip archives are extracted under the project, then any nested .../addons// (with plugin.cfg) is moved to project_root/addons// so res://addons// matches Godot. Editor plugins must be enabled by the user in Project Settings → Plugins (verify with godot_list_editor_plugins).

Inputs: asset_id (required), project_path, download_path. Returns: object

godot_edit_fileEdit Godot FileB

Edit a Godot file by replacing content.

Inputs: file_path (required), new_content (required), old_content (required), project_path. Returns: result

godot_execute_scriptExecute GDScriptC

Execute a GDScript in the Godot project context.

Inputs: script_content (required), godot_path, project_path. Returns: object

godot_find_assetsFind AssetsA
Read-only

Find assets by extension.

Inputs: extensions (required), relative, project_path. Returns: result

godot_find_by_patternFind Files by PatternC

Find files matching a pattern.

Inputs: pattern (required), project_path. Returns: result

godot_find_godot_executableFind Godot ExecutableA
Read-only

Find the Godot executable on the system.

Resolution order when GODOT_EXECUTABLE is unset: macOS: glob (where readable), Spotlight mdfind, find(1) under Applications, then directory scan, then PATH. Windows: where.exe for godot.exe / Godot.exe, then Downloads glob, then directory scan, then PATH. Linux: Downloads / portable names, directory scan, then PATH.

Returns: Dictionary with executable path and version info

Inputs: no named parameters. Returns: object

godot_find_projectFind Godot ProjectA
Read-only

Find the Godot project root by searching for project.godot.

Inputs: path. Returns: result

godot_find_unused_filesFind Unused FilesA
Read-only

Find files that may not be referenced in scenes or scripts.

Inputs: project_path. Returns: object

godot_generate_uidGenerate UIDA
Read-only

Generate a unique ID for Godot resources.

Returns: A unique ID string

Inputs: no named parameters. Returns: result

godot_get_asset_infoGet Asset DetailsB
Read-only

Get detailed information about an asset.

Inputs: asset_id (required). Returns: object

godot_get_file_infoGet File InfoC
Read-only

Get information about a file.

Inputs: file_path (required), project_path. Returns: object

godot_get_logGet Godot LogB
Read-only

Get recent Godot log entries.

Inputs: lines, project_path. Returns: object

godot_get_node_infoGet Node Type InfoB
Read-only

Get information about a Godot node type.

Inputs: node_type (required). Returns: object

godot_get_project_filesGet All Project FilesC
Read-only

Get all files in the project.

Inputs: project_path, include_assets. Returns: object

godot_get_project_infoGet Project InfoB
Read-only

Get detailed information about the Godot project.

Inputs: project_path. Returns: object

godot_get_project_settingsGet Project SettingsA
Read-only

Get project settings from project.godot (read-only).

editor_plugins_enabled lists res:// paths from [editor_plugins]; the user toggles plugins in the Godot editor — MCP does not write that section.

Inputs: project_path. Returns: object

godot_get_workspaceGet MCP workspace rootA
Read-only

Return the sandbox directory for this server.

Every project path, write, and Asset Library download must stay under this tree unless you change GODOT_MCP_ROOT and restart the server.

Returns: Absolute workspace path and configuration hints

Inputs: no named parameters. Returns: object

godot_list_autoloadList Autoload ScriptsB
Read-only

List autoload singletons.

Inputs: project_path. Returns: object

godot_list_editor_pluginsList Editor PluginsA
Read-only

List addon folders with plugin.cfg and which editor plugins are enabled in project.godot.

Use this (and godot_get_project_settings → editor_plugins_enabled) after the user enables plugins in the editor to verify before continuing. MCP installs addons (e.g. godot_download_asset) but does not modify [editor_plugins], to avoid fighting the open editor and external-reload dialogs.

Inputs: project_path. Returns: object

godot_list_projectsList Godot projects in workspaceA
Read-only

List every Godot project under the MCP sandbox directory.

Use this when the MCP process cwd is not inside a project or you need to pick among several games.

Returns: workspace root and a list of {root, name} for each project.godot found

Inputs: no named parameters. Returns: object

godot_list_resourcesList Resource FilesA
Read-only

List all .tres resource files in the Godot project.

Inputs: relative, project_path. Returns: result

godot_list_scenesList Scene FilesB
Read-only

List all .tscn scene files in the Godot project.

Inputs: relative, project_path. Returns: result

godot_list_scriptsList Script FilesA
Read-only

List all .gd script files in the Godot project.

Inputs: relative, project_path. Returns: result

godot_read_sceneRead Scene FileB
Read-only

Read and parse a scene file.

Inputs: scene_path (required), project_path. Returns: object

godot_read_scriptRead GDScriptA
Read-only

Read and parse a GDScript file.

Inputs: script_path (required), project_path. Returns: object

godot_refresh_projectRefresh Project CacheA

Refresh project cache after file changes.

Inputs: project_path. Returns: object

godot_run_gameRun Godot GameC

Run the Godot game.

Inputs: headless, godot_path, project_path, quit_after_seconds. Returns: object

godot_search_assetlibSearch Godot Asset LibraryC
Read-only

Search the official Godot Asset Library.

Inputs: query (required), page, sort, category, +2 more. Returns: object

godot_search_contentSearch File ContentsC

Search for content in Godot files.

Inputs: pattern (required), file_types, project_path. Returns: result

godot_validate_sceneValidate SceneC
Read-only

Validate a scene file.

Inputs: scene_path (required), project_path. Returns: object

godot_validate_scriptValidate ScriptB
Read-only

Validate a GDScript file.

Inputs: script_path (required), strict, project_path. Returns: object

godot_watch_filesList Watched FilesA

List scene, script, and/or resource files in the project (for monitoring or refresh).

This server does not run a background file watcher; use the returned paths with your editor or call godot_refresh_project() after external changes.

Inputs: project_path, watch_scenes, watch_scripts, watch_resources. Returns: object

godot_write_fileWrite Godot FileC

Write content to a file.

Inputs: content (required), file_path (required), project_path. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 40 tools

    Disambiguation2/5

    Many tools overlap in purpose, especially the retrieval/listing family: godot_get_project_files, godot_watch_files, godot_find_by_pattern, godot_find_assets, and the list_scenes/list_scripts/list_resources trio all inventory project files in similar ways. godot_create_code_template vs godot_create_script and godot_edit_file vs godot_write_file also have unclear boundaries, making tool selection ambiguous.

    Naming Consistency5/5

    All tool names follow the same godot_verb_noun pattern with snake_case throughout, making the naming convention highly predictable. Minor semantic issues like godot_watch_files not actually watching files do not break the syntactic consistency.

    Tool Count2/5

    40 tools is well beyond the 25-tool threshold for a cohesive set, and the high count is driven partly by redundant file-discovery operations. While Godot integration is a broad domain, this surface feels heavier than necessary and could be consolidated.

    Completeness3/5

    The server covers creation, reading, editing, validation, running, asset downloads, and plugin/autoload inspection, so core Godot workflows are mostly represented. However, there are no delete, rename, export, or project-settings update tools, and the read-only project settings plus overlapping file operations leave notable lifecycle gaps.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to create, edit, and run Godot 4.5+ games by providing tools for project scaffolding, scene manipulation, and engine interaction. It supports full game development workflows including node editing, script attachment, and project execution with debugging capabilities.
      24
      5
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      Enables AI assistants to interact with and manipulate Godot game engine projects, including creating projects, launching editor, managing scenes and nodes.
      12
      1
      ISC