io.github.sterion66/godot
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 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 项目。这可以防止助手读取或写入你系统上的任意路径。
创建默认文件夹(每台机器一次):
mkdir -p ~/godot-games将所有 Godot 游戏放在那里 — 每个游戏都是自己的子目录,包含
project.godot,例如:~/godot-games/ my-platformer/ ← open this folder in your editor project.godot ... another-game/ project.godot在
~/godot-games/.../your-game(或~/godot-games下的父文件夹)中打开你的 IDE 工作区,以便 MCP 进程可以从当前工作目录发现project.godot。自定义位置: 在启动服务器之前设置一个绝对路径:
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。如果该目录不存在,服务器会在启动时创建。运行时检查: 调用工具
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.pyHTTP 服务器
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.jsonWindows:
%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)。摘要:
工具 | 描述 |
| 显示 MCP 沙箱目录( |
| 定位项目根目录(向上遍历或工作区扫描) |
| 列出工作区下所有 |
| 在工作区下创建 |
| 获取项目详情 |
| 解析 project.godot(包含只读的 |
| 列出所有项目文件 |
| 重新扫描场景/脚本/资源数量 |
| 列出 |
| 列出 |
| 列出 |
| 列出自动加载单例 |
| 已安装的插件与 project.godot 中启用的插件对比(在 Godot 编辑器中启用插件) |
| 按扩展名查找 |
| 查找未被引用的资源 |
| Glob 模式搜索 |
| 在文件中进行正则搜索 |
| 创建新的 GDScript |
| 创建新场景 |
| 创建新资源 |
| 脚本模板 |
| 解析场景文件 |
| 解析 GDScript |
| 验证场景 |
| 验证语法 |
| 替换内容 |
| 写入文件 |
| 文件元数据 |
| 定位 Godot |
| Godot 版本 |
| 以无头模式运行 |
| 运行 GDScript |
| 读取日志 |
| 配置监视器 |
| 节点类型提示 |
| 生成 UID |
| 搜索资源库 |
| 资源详情 |
| 下载/解压资源(将嵌套的 |
| 搜索 GitHub |
编辑器插件: 本服务器不会在 project.godot 中写入 [editor_plugins](避免与打开的编辑器冲突)。通过上述工具安装插件;用户在 Godot 的 项目设置 → 插件 中启用插件;使用 godot_list_editor_plugins 进行验证。
资源
资源 | URI | 描述 |
项目信息 |
| 基本项目信息 |
项目概览 |
| 文件数量 |
工作区 |
| MCP 沙箱路径( |
运行时 |
| 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
在 GitHub 上创建一个空仓库(如果本地已有 README/license,请勿添加),例如
godot-mcp-server。添加远程仓库并推送:
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。
许可证
Available Tools
40 toolsgodot_browse_githubBrowse Godot GitHubBRead-only
Search for Godot-related repositories on GitHub.
Inputs: query (required), sort, repo_type. Returns: object
godot_check_versionCheck Godot VersionBRead-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 AssetsARead-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 ExecutableARead-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 ProjectARead-only
Find the Godot project root by searching for project.godot.
Inputs: path. Returns: result
godot_find_unused_filesFind Unused FilesARead-only
Find files that may not be referenced in scenes or scripts.
Inputs: project_path. Returns: object
godot_generate_uidGenerate UIDARead-only
Generate a unique ID for Godot resources.
Returns: A unique ID string
Inputs: no named parameters. Returns: result
godot_get_asset_infoGet Asset DetailsBRead-only
Get detailed information about an asset.
Inputs: asset_id (required). Returns: object
godot_get_file_infoGet File InfoCRead-only
Get information about a file.
Inputs: file_path (required), project_path. Returns: object
godot_get_logGet Godot LogBRead-only
Get recent Godot log entries.
Inputs: lines, project_path. Returns: object
godot_get_node_infoGet Node Type InfoBRead-only
Get information about a Godot node type.
Inputs: node_type (required). Returns: object
godot_get_project_filesGet All Project FilesCRead-only
Get all files in the project.
Inputs: project_path, include_assets. Returns: object
godot_get_project_infoGet Project InfoBRead-only
Get detailed information about the Godot project.
Inputs: project_path. Returns: object
godot_get_project_settingsGet Project SettingsARead-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 rootARead-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 ScriptsBRead-only
List autoload singletons.
Inputs: project_path. Returns: object
godot_list_editor_pluginsList Editor PluginsARead-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 workspaceARead-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 FilesARead-only
List all .tres resource files in the Godot project.
Inputs: relative, project_path. Returns: result
godot_list_scenesList Scene FilesBRead-only
List all .tscn scene files in the Godot project.
Inputs: relative, project_path. Returns: result
godot_list_scriptsList Script FilesARead-only
List all .gd script files in the Godot project.
Inputs: relative, project_path. Returns: result
godot_read_sceneRead Scene FileBRead-only
Read and parse a scene file.
Inputs: scene_path (required), project_path. Returns: object
godot_read_scriptRead GDScriptARead-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 LibraryCRead-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 SceneCRead-only
Validate a scene file.
Inputs: scene_path (required), project_path. Returns: object
godot_validate_scriptValidate ScriptBRead-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
Scored across 40 tools
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.
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.
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.
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
Related MCP Connectors
Let your coding agent read your GameSalad projects, and edit them live in Creator on Pro and Edu.
Create and edit PlayableMaker playable ads from chat and download them as projects.
Project memory, documentation and controlled secret access for AI coding agents.
Shiny Gen (ShinyGen), AI game maker: build, run and play-test Godot and retro console games live
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.245MIT
- AlicenseCqualityDmaintenanceEnables AI assistants to interact with and manipulate Godot game engine projects, including creating projects, launching editor, managing scenes and nodes.121ISC
- AlicenseAqualityDmaintenanceEnables AI agents to launch, edit, debug, and test Godot game projects with comprehensive scene and script manipulation tools.501MIT
- AlicenseCqualityCmaintenanceEnables AI agents to interact with the Godot game engine, including project inspection, scene/script parsing, headless exports, runtime control with live scene-tree inspection and evaluation, and API documentation search.1005MIT