关于 glade-mcp
glade-mcp 将 AI 客户端连接到 Unity 和 Godot 编辑器,用于游戏开发。它通过自动检测当前编辑器的 MCP 服务,提供引擎专用工具、项目编辑、玩法脚手架和验证工作流。
主要功能
- 01连接 Unity 和 Godot 编辑器
- 02编辑场景、脚本和资源
- 03生成玩法脚手架
- 04通过截图和运行时检查验证项目
- 05构建和导出项目
适用场景
- 01在编辑器中创建玩法系统
- 02查找并重命名脚本引用
- 03开发时检查运行时行为
- 04构建或导出编辑器项目
MCP 相关
MCP 服务会检测正在运行的 Unity 或 Godot 编辑器,并向 MCP 客户端公开相应工具和资源。它通过编辑器桥接在本地端口建立连接。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
工具
本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。
详细介绍
GladeKit MCP
将 Cursor、Claude Code、Windsurf、Claude Desktop 和其他 AI 客户端直接连接到 Unity 或 Godot 编辑器。
**Unity(2021.3+):**涵盖 20 个类别的 275 个工具、完整的 Unity 感知型系统提示词、GLADE.md 项目上下文、脚本语义搜索、技能校准、免费的 CC0 资源管线,以及具备 RAG 和跨会话记忆的云端智能层。
**Godot(4.3+):**涵盖 17 个类别的 115 个原生工具,包括场景/节点、脚本、资源、信号、物理和编辑时空间查询、2D(精灵、瓦片地图、视差)、音频、粒子、动画和 AnimationTree、摄像机、导航、UI、光照和 WorldEnvironment、运行时、导出及项目内省。
**两种引擎均支持:**一键生成经过审核的游戏玩法框架(控制器、敌人、战斗、菜单、存档系统)、验证循环(look_at_game_view 截图、运行时事件观察、可玩性探测)、精确脚本编辑并支持真正的 find_references / rename_symbol,以及构建/导出工具,让 Agent 能交付它构建的内容。
MCP 服务会自动检测正在运行的编辑器(Unity 使用 :8765,Godot 使用 :8766),并提供相应的工具集。

快速开始
1. 安装编辑器桥接程序
GladeKit MCP 同时支持 Unity 和 Godot。两个桥接程序都位于此仓库中:unity-bridge/ 是一个 UPM 包;godot-bridge/ 封装了位于 godot-bridge/addons/com.gladekit.mcp-bridge/ 的编辑器插件。请安装适用于你的引擎的版本。
Unity(2021.3+)
在 Unity 中,打开 Window > Package Manager > + > Add package from git URL...
https://github.com/Glade-tool/glade-mcp.git?path=/unity-bridge
Unity 桥接程序会自动在 localhost:8765 上启动。Window > GladeKit MCP 会显示桥接程序/客户端状态,并提供一键 Copy MCP Config 和 Copy Unity AI Gateway Config 按钮。
Godot(4.3+)
- 从最新的 Godot 桥接程序发布页下载
com.gladekit.mcp-bridge.zip。(请在 Assets 下下载 zip 文件,而不是“Source code”。)也可以直接从源代码安装:从此仓库复制godot-bridge/addons/com.gladekit.mcp-bridge/。 - 将
com.gladekit.mcp-bridge/文件夹移入项目的addons/目录,使最终路径为<your-godot-project>/addons/com.gladekit.mcp-bridge/plugin.cfg。 - 在 Godot 中:Project → Project Settings → Plugins → 启用 GladeKit MCP Bridge。
Godot 桥接程序会自动在 localhost:8766 上启动。你应该会在编辑器的 Output 面板中看到确认信息:
[GladeKit MCP Bridge] listening on ws://127.0.0.1:8766 (v0.7.14, 115 tools registered, thread-polled at 200Hz)
桥接程序会将每个会话的身份验证令牌写入 ~/.gladekit/godot-bridge-8766.token;MCP 服务会自动读取该令牌,因此网页无法通过本地套接字驱动你的编辑器。
**支持:**Godot 4.3+ GDScript 项目、Forward+ 和 Compatibility 渲染器、2D 和 3D。**暂不支持:**Godot Mono / C# 项目。桥接程序仅用于编辑器,不会在导出的游戏中运行。
引擎自动检测:MCP 服务会在启动时探测两个端口,并提供相应的工具集。需要同时运行两个编辑器?设置 GLADEKIT_MCP_FORCE_ENGINE=unity 或 =godot,即可指定引擎。
2. 连接 AI 客户端
安装 uv(一次性操作):
- Mac/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh - Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
然后将 MCP 配置添加到 AI 客户端。客户端会自动启动 MCP 服务,无需手动启动服务。
Claude Code
选项 A:一行命令(推荐)
- Mac/Linux:
claude mcp add --transport stdio gladekit-mcp --scope user -- uvx gladekit-mcp - Windows:
claude mcp add --transport stdio gladekit-mcp --scope user -- cmd /c uvx gladekit-mcp
选项 B:手动配置
如果你克隆了此仓库,.mcp.json 会自动连接。否则,请将以下内容添加到 Claude Code MCP 设置中:
{
"mcpServers": {
"gladekit-mcp": {
"command": "uvx",
"args": ["gladekit-mcp"]
}
}
}
Cursor
Cursor Settings > MCP > Add new MCP server:
{
"mcpServers": {
"gladekit-mcp": {
"command": "uvx",
"args": ["gladekit-mcp"]
}
}
}
Claude Desktop
编辑 ~/Library/Application Support/Claude/claude_desktop_config.json(Mac)或 %APPDATA%\Claude\claude_desktop_config.json(Windows):
{
"mcpServers": {
"gladekit-mcp": {
"command": "uvx",
"args": ["gladekit-mcp"]
}
}
}
Cline (VS Code extension)
打开 Cline 的 MCP 设置文件(首次使用 MCP 时自动创建):
- Mac:
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json - Windows:
%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json - Linux:
~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
添加:
{
"mcpServers": {
"gladekit-mcp": {
"command": "uvx",
"args": ["gladekit-mcp"]
}
}
}
Windsurf
在 Windsurf 中,打开 Windsurf Settings → MCP Servers → Open MCP Registry,然后点击设置(齿轮)图标,打开 mcp_config.json。添加以下代码片段(或直接编辑 ~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"gladekit-mcp": {
"command": "uvx",
"args": ["gladekit-mcp"]
}
}
}
Unity AI Gateway (native in-editor)
Unity 内置的 AI Assistant 可通过 MCP 连接 GladeKit。这样,你就能直接在 Unity Editor 中使用 GladeKit 的 275 个工具,无需外部 AI 客户端。
要求: Unity 6000.3+,并安装 AI Gateway 包([email protected])
- 在 Unity 中,前往 Edit > Project Settings > AI > MCP Servers
- 点击 Open Config File 并粘贴以下内容(或使用 Window > GladeKit MCP > Copy Unity AI Gateway Config):
{
"enabled": true,
"path": "",
"mcpServers": {
"gladekit-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["gladekit-mcp"]
}
}
}
- 在 Path Configuration 下,将终端中的 PATH 粘贴到 User Path,以便 Unity 找到
uvx。获取 PATH 的方法:- Mac/Linux:
echo $PATH - Windows:
echo %PATH%
- Mac/Linux:
- 点击 Refresh Config File and Reload Servers
- 确认 Servers 部分中的服务显示为 StartedSuccessfully
提示: 如果找不到
uvx,请将其所在目录添加到配置中的path字段(例如,Mac 上的"/opt/homebrew/bin"或 Windows 上的"C:\\Users\\<you>\\.local\\bin")。或者,使用pip install gladekit-mcp,并设置"command": "python"和"args": ["-m", "gladekit_mcp"]。
故障排除: 如果服务显示为 FailedToStart,请点击 Inspect 查看错误详情。最常见的原因是 PATH 不正确——Unity 的 PATH 与终端中的 PATH 不同。请参阅下文的故障排除部分。
付费套餐(
GLADEKIT_API_KEY): 若要在任何客户端上启用 RAG 知识库和跨会话记忆,请将密钥添加到配置的env字段。请参阅下文的云端智能。
VS Code (GitHub Copilot)
将以下内容添加到工作区中的 .vscode/mcp.json:
{
"servers": {
"gladekit-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["gladekit-mcp"]
}
}
}
为什么选择 GladeKit?
| 特性 | GladeKit MCP | unity-mcp (CoplayDev) | godot-mcp (Coding-Solo) |
|---|---|---|---|
| 引擎 | Unity 和 Godot,由单个服务自动检测 | Unity | Godot |
| 工具 | 275 个 Unity 工具 + 115 个 Godot 工具,粒度细致 | 48 个整合工具(action 枚举) | 14 个 |
| 编辑器连接 | 实时编辑器会话(HTTP :8765 / WebSocket :8766) | 实时编辑器会话 | 每次调用都会启动 godot --headless,并在磁盘上编辑 .tscn |
| 游戏玩法脚手架生成器 | 一次调用即可生成经过验证的模板——控制器、敌人、投射物、生命值 + HUD、游戏管理器、菜单、移动平台、存档系统 | 无 | 无 |
| 验证循环 | look_at_game_view 截图、运行时事件流、可玩性探测、修复后再验证门控、compile_scripts | 截图、读取控制台、测试运行器 | run_project + 原始 stdout |
| 脚本编辑 | 大纲 / 局部读取、锚点编辑、真正的 find_references / rename_symbol(词法扫描器) | 锚点 / 正则表达式编辑、Roslyn 验证 | 无脚本工具 |
| 构建 / 导出 | 支持两种引擎(build_player、export_project) | Unity | 无(仅 MeshLibrary) |
| 资源 | 免费的 CC0 流程,带许可证审计 | AI 生成(自带 Tripo / Meshy / fal 密钥) | 无 |
| 项目上下文 | GLADE.md + 实时提示词(渲染管线、输入系统、技能水平) | 静态指令 | 无 |
| 脚本搜索 | 通过 OpenAI embeddings 进行语义搜索(自备密钥) | 正则表达式 find_in_file | 无 |
| 记忆 | 会话内(remember_for_session)+ 跨会话(云端) | 无 | 无 |
| 安全性 | 编辑操作支持撤销、修改前备份、覆盖保护、按会话进行令牌身份验证、只读模式 | SHA 保护的脚本编辑 | 无 |
| 测试 | 269 个 pytest + 覆盖 37 个用例的评测(针对 3 个 MCP SDK 版本)、schema↔bridge 一致性保护、Unity NUnit + Godot GUT 测试套件 | Unity CI 矩阵 + NL 套件 | 无 |
| 许可证 | MIT | MIT | MIT |
| 已于 2026-08-29 对照 unity-mcp v10.1.2 和 godot-mcp 0.1.1 的源码进行验证。godot-mcp 是星标数最多的 Godot 服务;最接近的活跃编辑器内替代方案 godot-ai(46 个工具)支持截图和批量执行,但不支持脚手架生成、重构、资源管线、导出或记忆功能。 |
所有核心功能均免费且可在本地运行。云端智能层为可选功能,需要 GLADEKIT_API_KEY。
功能
275 个 Unity 工具 + 115 个 Godot 工具
Unity(20 个类别): 场景 • GameObjects • 脚本 • 预制体 • 材质 • 光照 • VFX 和音频 • 动画 • IK • 物理(3D 和 2D) • Tilemaps • 摄像机 • UI • 输入系统 • 地形和 NavMesh • 性能分析器 • 游戏玩法脚手架生成器 • 运行时和诊断 • 构建 • 资源管线
全部 275 个工具均可调度。Claude Code 默认会看到约 90 个精选核心工具(Claude Code 的实际工具数量上限为 128 个;Unity AI Gateway 受云端令牌预算限制)。使用 get_relevant_tools 可发现用于专业工作的扩展工具(混合树、NavMesh、IK、Cinemachine 等)。
5 个元工具: get_relevant_tools(基于任务的工具发现 + RAG 上下文)、remember_for_session(存储事实)、recall_session_memories(检索事实)、batch_execute(多步工具调度)、search_project_scripts(语义代码搜索,仅限 Unity)。前四个工具适用于两种引擎。
9 个 MCP 资源(Unity): 桥接健康状态、项目上下文、项目信息、场景层级、项目脚本、当前选择、GLADE.md、会话记忆和批处理规范遥测数据。
Godot(17 个类别): 全部 115 个工具均直接开放(无需核心工具筛选),另有四个引擎无关的元工具。只读工具带有 MCP readOnlyHint 注解,客户端可据此自动批准。
一次调用即可生成游戏玩法脚手架
经过验证、可自动连接的模板,会原样写入可靠脚本并围绕脚本组装场景,同时保留从头编写脚本时容易遗漏的游戏手感细节(土狼时间、跳跃缓冲、可变跳跃高度、对角线归一化)。再次运行时会复用已有内容,而不会重复创建。
- 玩家:
create_third_person_controller(3D,两种引擎均支持)、create_platformer_controller/create_top_down_controller(Unity)、create_2d_controller(Godot)。 - 战斗:
create_projectile、create_health、create_health_bar、create_enemy(Unity)/create_enemy_2d+create_enemy_3d(Godot)、create_hit_vfx。 - 游戏循环:
create_game_manager(分数、生命、胜利/失败)、create_collectible、create_hazard、create_level_system、create_loot_drop、create_save_system。 - 流程与手感:
create_main_menu、create_pause_menu、create_scene_transition、create_moving_platform、create_screen_shake、create_juice、create_particles_2d/_3d、create_sound_effects。
批量布局工具(set_transform_batch、set_node_transform_batch、arrange_nodes、snap_to_ground)可通过一次调用放置数十个对象,无需逐个往返调用。
验证构建成果
- **查看画面:** `look_at_game_view` 会返回渲染视图的截图,帮助模型发现仅靠检查无法察觉的隐藏、缺失或位置错误的对象。 - **观察运行:** `start_runtime_observation` / `get_runtime_events` 会从运行会话中持续传输带游标和指纹的错误信息流;原始日志可使用 `get_unity_console_logs` / `get_godot_console_logs` 获取。 - **进行游戏测试:** `start_playability_probe`(Unity)和 `run_gameplay_probe`(Godot)会通过输入控制玩家并报告 PASS/FAIL;Godot 的 `run_project` 提供 `verify` 模式,可运行、捕获并报告结果。 - **编译并交付:** `compile_scripts`(Unity);`build_player` + `get_build_status`(Unity),以及 `create_export_preset` + `export_project`(Godot,包括 Web)。 - **诊断卡顿(Godot):** 编辑器主线程看门狗会将“超时”转化为“编辑器已卡死 12 秒——请关闭模态对话框”,并提供 `possible_solutions`。精准脚本编辑
get_script_content 支持大文件的轮廓模式(结构概览)和按行范围读取;modify_script 可应用基于锚点的编辑。find_references 和 rename_symbol 使用词法扫描器(支持 C# 和 GDScript),只匹配完整标识符,因此重命名前就能看到实际影响范围。除非用户明确要求,否则 create_script / modify_script 不会覆盖现有项目脚本。
GLADE.md
在 Unity 项目根目录中创建 GLADE.md 文件。MCP 服务会读取该文件,并将其注入每个请求中。它可作为永久上下文层,始终提供游戏的设计意图、约定和限制。
# My Game
Genre: 3D platformer
Player: CharacterController, double jump enabled
Art style: pixel art, 16x16 sprites
Naming: PascalCase for scripts, snake_case for folders
脚本语义搜索
在 MCP 配置的 env 字段中设置 OPENAI_API_KEY,服务便会根据语义相似度为项目脚本排序。询问“敌人是如何生成的?”,即可找到相关脚本,即使脚本名不是 EnemySpawner。
所需内容均随软件包提供,无需安装标志或额外组件。可在 platform.openai.com/api-keys 获取密钥(按量付费,每次搜索只需几分钱,使用 text-embedding-3-small)。
{
"mcpServers": {
"gladekit-mcp": {
"command": "uvx",
"args": ["gladekit-mcp"],
"env": { "OPENAI_API_KEY": "sk-..." }
}
}
}
没有密钥时,search_project_scripts 仍会返回脚本,只是不进行排序。密钥只会发送到 OpenAI 的嵌入端点。
技能水平校准
服务会跟踪你消息中的词汇,并判断你是 Unity 初学者还是专家。初学者会收到通俗易懂的解释和鼓励性的措辞;专家则会收到简洁、专业的回复。校准结果会保存到项目中的 .gladekit/skill_level.json。
资源流程(免费 CC0 导入)
提供三个工具,可在两种引擎中直接通过 AI 客户端查找并导入免费且可商用的资源。所有资源均为 CC0(公有领域,无需署名)。v1 随附 Kenney.nl 资源包(每周更新目录);其他提供方(Freesound、Quaternius、AI 生成)已列入路线图。
| 工具 | 用途 |
|---|---|
find_asset | 按描述、资源类型、风格和许可证搜索并排序候选资源。只读,不会将操作分派给编辑器。 |
import_asset | 下载、解压、放置到 Assets/(或 res://)下,为资源类型配置导入设置,并写入包含许可证元数据的 .gladekit-asset.json 旁车文件。需要明确提供 licenseAcknowledged: true。 |
list_imported_assets | 遍历项目中的旁车文件并显示许可证审计信息(许可证数量、需要署名的数量)。适合在商业发行前使用。 |
示例工作流(Cursor、Claude Code、Windsurf 使用相同的模式):
你: 我正在制作一款 2D 平台游戏原型,需要临时使用角色和图块美术资源。帮我找一些免费的。
AI 调用 find_asset:
{
"description": "platformer character and tiles",
"asset_type": "sprite_2d",
"max_results": 5
}
结果(已截断):
{
"success": true,
"candidates": [
{
"id": "kenney/platformer-pack-redux",
"name": "Platformer Pack Redux",
"description": "360+ side-scrolling platformer sprites: characters, enemies, tiles, items, hazards.",
"license": "CC0-1.0",
"license_summary": "Public domain. No attribution required for any use, including commercial.",
"official_page": "https://kenney.nl/assets/platformer-pack-redux",
"approx_assets": 360,
"score": 0.92
},
{ "id": "kenney/pixel-platformer", "score": 0.71, ... },
{ "id": "kenney/tiny-town", "score": 0.45, ... }
],
"count": 3
}
你: 就选 Platformer Pack Redux 吧。把它导入到
Assets/Sprites/Platformer/。我接受 CC0 许可证。
AI 调用 import_asset:
{
"candidateId": "kenney/platformer-pack-redux",
"assetType": "sprite_2d",
"licenseAcknowledged": true,
"targetPath": "Assets/Sprites/Platformer/"
}
MCP 服务在本地解析下载 URL(目录随服务一同打包,无需依赖云端),并将其传递给 Unity 桥接程序。桥接程序会下载、解压、为每个精灵配置 TextureImporter(Texture Type = Sprite、Filter Mode = Point、Uncompressed),然后写入许可证旁车文件。结果:
{
"success": true,
"message": "Imported 360 file(s) from kenney/platformer-pack-redux to Assets/Sprites/Platformer/",
"downloadedBytes": 1842340,
"importedFileCount": 360,
"configuredImportSettings": 354,
"license": "CC0-1.0",
"sidecarPath": "Assets/Sprites/Platformer/.gladekit-asset.json"
}
精灵会显示在 Unity Project 窗口中,可以直接拖入场景。
你: 发布之前,审计一下我导入的资源。有没有需要署名的?
AI 调用 list_imported_assets:
{
"success": true,
"count": 1,
"licenseCounts": { "CC0-1.0": 1 },
"attributionRequiredCount": 0,
"entries": [
{
"candidate_id": "kenney/platformer-pack-redux",
"license": "CC0-1.0",
"asset_type": "sprite_2d",
"imported_at": "2026-05-10T09:37:42Z",
"target_path": "Assets/Sprites/Platformer/",
"imported_file_count": 360,
"sidecar_path": "Assets/Sprites/Platformer/.gladekit-asset.json"
}
]
}
CC0 无需署名;审计报告中没有需要署名的项目。如果之后导入了 CC-BY 资源,它会显示在这里,提醒你注明出处。
安全性与许可证规范:
- 大模型看不到下载 URL。URL 解析在云端/MCP 端进行;如果解析后的字段缺失或由大模型注入,桥接工具会拒绝操作。
- 每次调用
import_asset都必须提供licenseAcknowledged: true。没有该参数,桥接程序会拒绝操作。未经用户明确确认,不要设置该参数。 - 下载前,桥接程序会根据每个提供方的允许列表,验证
_resolvedUrl的主机名(AssetPipelineGuard.IsResolvedUrlHostAllowed)。即使客户端绕过云端和 MCP 的预处理环节,也无法偷偷传入任意下载 URL;未知主机名会被默认拒绝。仅支持 HTTPS。 - 每个导入的资源包都会获得一个
.gladekit-asset.json旁车文件,其中记录候选资源 ID、提供方、许可证、署名字符串、源 URL 和时间戳。list_imported_assets会读取这些文件以生成审计报告。 - 桥接端通过
AssetPipelineGuard控制资源管线工具。配置错误的客户端无法绕过此限制。
禁用管线(适用于工作室或精选资源工作流):
在 MCP 服务的环境中设置 GLADEKIT_MCP_DISABLE_ASSET_PIPELINE=1,即可完全停用这三个工具。它们不会出现在工具列表中,分派请求时也会返回明确的错误。对于已有受管资源工作流的项目(例如由 Perforce 跟踪的资源库、内部资源存储库),不适合使用 AI 驱动的外部下载;建议此类项目采用此设置。
{
"mcpServers": {
"gladekit-mcp": {
"command": "uvx",
"args": ["gladekit-mcp"],
"env": { "GLADEKIT_MCP_DISABLE_ASSET_PIPELINE": "1" }
}
}
}
Unity 桥接程序通过 EditorPrefs(GladeAI.AssetPipelineEnabled,默认值为 true)实施相同的限制。可通过 POST http://localhost:8765/api/settings { "assetPipelineEnabled": false } 切换此设置。
安全与防护
- **可撤销:**搭建脚手架和批量编辑会登记到编辑器的撤销栈(Unity),或在修改前于
.gladekit-backups/中创建备份,并支持通过节点撤销(Godot)。create_script/modify_script未显式指定标志时,会拒绝覆盖项目中的实际脚本。 - **仅限回环地址:**两个桥接服务都绑定到
127.0.0.1。Godot 桥接服务要求每个请求都携带会话专用令牌(~/.gladekit/godot-bridge-<port>.token),但health除外,以防止跨站 WebSocket 偷偷发起驱动请求。Unity 桥接服务会对文件端点实施本地主机访问控制和路径遍历防护。 - **运行模式安全:**编辑器运行时,编辑工具会拒绝执行;只读工具在两种模式下都可运行。
- 只读会话:
GLADEKIT_GODOT_READ_ONLY=1(或在项目设置中设置gladekit/read_only_mode)会让 Godot 桥接服务拒绝所有会修改内容的工具,适用于审计、审查和演示。
云端智能
在 MCP 配置的 env 字段中设置 GLADEKIT_API_KEY,即可启用云端功能:
- RAG 知识库 -
get_relevant_tools会查询经过整理且适配引擎的知识库(API 修正、错误模式),并将结果与工具推荐一同注入。Godot 会话会检索 Godot 文档,而非 Unity 内容。 - 跨会话持久记忆 - 使用
remember_for_session存储的事实会跨会话保留,并重新注入系统提示词。 - 约定提取 - 从积累的记忆中提炼编码模式(命名、架构、偏好),并在后续会话中提供。
所有云端功能都能优雅降级:如果缺少密钥或无法连接云端,一切仍可正常运行。
{
"mcpServers": {
"gladekit-mcp": {
"command": "uvx",
"args": ["gladekit-mcp"],
"env": { "GLADEKIT_API_KEY": "your-api-key" }
}
}
}
传输方式(stdio + streamable HTTP)
GladeKit MCP 支持两种传输方式。stdio 是默认方式,适用于所有 MCP 客户端——以上所有配置都使用 stdio。服务端同时支持 MCP SDK 1.x 和 2.x(mcp[cli]>=1.10,<3),并在最低版本、最新的 1.x 和最新的 2.x 上进行测试。
Streamable HTTP 适用于偏好基于 URL 配置的客户端(Claude Desktop URL 模式、自定义客户端)。手动启动服务端,然后将客户端指向该 URL:
# Defaults: host=127.0.0.1, port=8767, path=/mcp
gladekit-mcp --transport http
# Custom host/port/path
gladekit-mcp --transport http --host 127.0.0.1 --port 9000 --path /mcp
端点:
POST/GET/DELETE http://127.0.0.1:8767/mcp- MCP streamable-HTTP 端点GET http://127.0.0.1:8767/health- 存活检查
安全默认设置:
- 仅绑定到回环地址(
127.0.0.1)。使用--host 0.0.0.0可开放到局域网,但需主动选择。 - 回环地址绑定时会启用 DNS 重绑定防护:
Host标头不是127.0.0.1:<port>或localhost:<port>的请求会被拒绝,并返回421 Misdirected Request。 - 非回环地址绑定时会禁用重绑定防护(网络安全由你负责),并在启动时打印警告。
客户端配置示例:
{
"mcpServers": {
"gladekit-mcp": {
"url": "http://127.0.0.1:8767/mcp"
}
}
}
环境变量
MCP 服务(在客户端配置的 env 字段中设置):
| Variable | Required | Description |
|---|---|---|
UNITY_BRIDGE_URL | No | Unity 桥接 URL(默认值:http://localhost:8765) |
GODOT_BRIDGE_URL | No | Godot 桥接 URL(默认值:ws://localhost:8766/) |
GLADEKIT_MCP_FORCE_ENGINE | No | unity 或 godot——当两个编辑器都打开时,跳过自动检测 |
OPENAI_API_KEY | No | 启用基于嵌入的脚本语义搜索(获取一个) |
GLADEKIT_API_KEY | No | 启用 RAG 知识库、跨会话记忆和约定提取 |
GLADEKIT_MCP_DISABLE_ASSET_PIPELINE | No | 设置为 1 可屏蔽 find_asset / import_asset / list_imported_assets(精选资源工作流) |
GLADEKIT_MCP_SUPPRESS_BRIDGE_WARNING | No | 设置为 1 可关闭 Unity 或 Godot 桥接版本低于推荐版本时的 stderr 警告 |
Godot 桥接(启动 Godot 之前在 shell 中设置):
| Variable | Description |
|---|---|
GLADEKIT_GODOT_BRIDGE_PORT | 监听端口(默认值为 8766) |
GLADEKIT_GODOT_READ_ONLY | 设置为 1,拒绝此编辑器会话的所有修改类工具 |
GLADEKIT_GODOT_NO_AUTH | 设置为 1,禁用每会话令牌身份验证(适用于较旧的客户端;选择启用) |
故障排除
Unity 桥接无法连接
- 打开 Unity 并等待其完成资源导入——桥接会自动启动
- 在 Unity 中检查 Window > GladeKit MCP——Bridge 和 AI Client 指示器会显示连接状态;Restart 会重新绑定服务,Diagnostics 面板会显示近期桥接故障
- 确认没有其他程序占用端口 8765:
lsof -i :8765(Mac/Linux)或netstat -ano | findstr 8765(Windows)
Godot 桥接无法连接
- 确认插件已启用,且 Output 面板显示
listening on ws://127.0.0.1:8766;绑定失败时会打印GLADEKIT_GODOT_BRIDGE_PORT覆盖设置说明 - 工具错误中出现
authentication failed:MCP 服务无法读取~/.gladekit/godot-bridge-8766.token。重启 Godot(它会重新写入令牌),或者对于较旧的客户端,在启动 Godot 前设置GLADEKIT_GODOT_NO_AUTH=1 - 对话框打开时工具调用超时:编辑器的主线程被阻塞。关闭对话框;错误信息会指出卡顿时长
AI 客户端找不到 uvx
- 安装 uv:
curl -LsSf https://astral.sh/uv/install.sh | sh(Mac/Linux)或pip install uv - 或者使用
pip install gladekit-mcp,并将配置命令从"uvx"改为"python",参数设为["-m", "gladekit_mcp"]
Claude Code 中未显示工具
- Claude Code 实际上最多支持约 128 个工具。GladeKit 默认显示约 90 个精选核心工具——这是有意为之。全部 275 个工具都可调用:使用
get_relevant_tools按任务描述查找扩展工具。
未加载 GLADE.md
- 文件名必须准确为
GLADE.md(Mac/Linux 上区分大小写),并放置在 Unity 项目根目录下(与Assets/、Packages/、ProjectSettings/同级)
Stderr 警告:Unity bridge X.Y.Z is older than recommended
-
Unity 会缓存 UPM Git 包,且不会重新获取,因此
?path=unity-bridge安装版本会随着时间推移逐渐落后于main。通过 Unity → Window > Package Manager > GladeKit MCP Bridge > Update 更新,或将清单条目固定到特定标签,以便明确控制后续更新:"com.gladekit.mcp-bridge": "https://github.com/Glade-tool/glade-mcp.git?path=unity-bridge#v0.7.23" -
同一条警告也会作为一次性前缀出现在下一条工具响应中,方便你在聊天中看到。若要同时关闭这两处提示:在 MCP 客户端配置的
env中添加"GLADEKIT_MCP_SUPPRESS_BRIDGE_WARNING": "1"。对于 Godot,请用最新版本的 zip 替换 addon 文件夹。
Unity AI Gateway - 服务显示 FailedToStart
- 在 Servers 部分点击 Inspect 查看错误消息
- 最常见的原因:Unity 找不到
uvx。在 Path Configuration 下,将终端中的完整 PATH 粘贴到 User Path,然后点击 Refresh Config File and Reload Servers - 在 Windows 上:在 Command Prompt 中运行
echo %PATH%。在 Mac/Linux 上:运行echo $PATH - 另一种方法:使用
pip install gladekit-mcp,并将命令设为"python",参数设为["-m", "gladekit_mcp"],这样就无需依赖uvx的 PATH - 先在 Unity 外验证:在终端中运行
uvx gladekit-mcp(你应该能在 stderr 中看到gladekit-mcp v...横幅)
架构
[AI Client: Cursor / Claude Code / Windsurf / Claude Desktop / Unity AI Gateway]
|
| stdio or HTTP MCP protocol
v
[gladekit_mcp Python process]
bridge.py -> probes :8765 (Unity, HTTP) and :8766 (Godot, WebSocket), picks the engine
prompts.py -> system prompt (auto-reads render pipeline, input system, GLADE.md)
tools/ -> 275 Unity tool schemas + dispatch schemas/godot/ -> 115 Godot tool schemas
asset_pipeline/ -> bundled CC0 catalog + URL resolution
cloud.py -> optional GLADEKIT_API_KEY -> api.gladekit.com
| |
| HTTP localhost:8765 | WebSocket localhost:8766 (+ session token)
v v
[Unity Bridge -- C# Editor extension] [Godot Bridge -- GDScript EditorPlugin]
unity-bridge/ (UPM package) godot-bridge/addons/com.gladekit.mcp-bridge/
UnityBridgeServer.cs -> HttpListener ws_server.gd -> TCPServer + WebSocketPeer
275 ITool implementations 115 tool implementations (main-thread dispatch)
UnityContextGatherer, PlayModeObserver, context_gatherer, play_session_manager,
BackupManager, BuildManager backup_manager, export_manager, bridge_auth
参与贡献
每个桥接程序都是其工具的事实来源;Python 服务会镜像其架构。每当 mcp-server/、unity-bridge/ 或 godot-bridge/ 有变更时,CI 都会运行(包括 ruff、pytest,以及针对三个 MCP SDK 版本的评估测试框架);如果某个参数只存在于一侧,架构↔桥接程序字段一致性测试就会失败。添加一个工具需要进行三处更改。
Unity
- C# 实现(
unity-bridge/Editor/Tools/Implementations/<Category>/MyTool.cs):
public class MyTool : ITool
{
public string Name => "my_tool";
public string Execute(Dictionary<string, object> args)
{
// ... Unity Editor API calls ...
return ToolUtils.CreateSuccessResponse("Done", extras);
}
}
-
C# 注册(
unity-bridge/Editor/Tools/Registrars/<Category>Tools.cs):添加Register(new MyTool());。注册是显式的——未注册的工具可以正常编译,但在分发时会返回 "Tool was blocked from executing or null."。 -
Python 架构(
mcp-server/src/gladekit_mcp/tools/<category>.py):按照现有格式(OpenAI 函数调用架构)在该类别的工具列表中添加一项。
Godot
-
GDScript 实现(
godot-bridge/addons/com.gladekit.mcp-bridge/tools/implementations/<category>/my_tool.gd),继承i_tool.gd;在_init()中设置tool_name和requires_edit_mode,并返回ToolUtils.success(...)/ToolUtils.error(...)。 -
注册:在
godot-bridge/addons/com.gladekit.mcp-bridge/bridge/tool_registry.gd中注册(register_tool(MyTool.new()))。 -
Python 架构(
mcp-server/src/gladekit_mcp/schemas/godot/<category>.py)。
有关传输协议和 GUT 测试设置,请参阅 godot-bridge/README.md;有关发布历史,请参阅 mcp-server/CHANGELOG.md。
许可证: MIT,详见 LICENSE。
GladeKit 桌面应用 是一款独立的商业产品,在此 MCP 服务基础上增加了流式传输、遗漏恢复和记忆界面。
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。