使用说明
Unity MCP——Unity编辑器的AI助手集成
Unity原生 模型上下文协议 (MCP)服务器,用于AI驱动的游戏开发。将Claude、Codex、Cursor和其他AI助手直接连接到Unity编辑器——不需要Node.js、Python或外部运行时。安装软件包并开始构建。
v2.2中的新功能
Canvas UI构建工具、输入动作管理、项目设置管理、批处理执行和合并视觉捕捉。
特性
- 100%Unity原生 --作为单个包完全在Unity编辑器中运行。无需安装或维护sidecar进程。
- 零遥测 --完全私密。没有数据离开你的机器。
- 51个内置工具 --创建游戏对象、运行测试、构建项目、管理场景、构建Canvas UI、管理输入操作等等。
- 23个资源+6个资源模板 --通过URI模式对项目设置、场景状态、控制台输出等进行只读访问。
- 4个工作流提示 --为常见的Unity任务预构建提示模板。
- 4个内置食谱 --一个调用场景设置模板(FPS原型、UI画布、3D模板、物理游乐场)。
- 检查点系统 --使用diff支持,在破坏性操作之前保存和恢复场景状态。
- 视觉捕捉 --将游戏/场景视图截图直接发送给AI助手进行视觉分析。
- 场景诊断 --在一次通话中进行叙事场景总结和结构化问题扫描。
- 远程访问 -使用TLS加密和API密钥身份验证从网络上的其他设备连接。
- 活动日志 --从编辑器窗口实时监控MCP请求和响应。
- 每个动作注释 --安全提示(
readOnlyHint,destructiveHint)每个动作都能解决,因此即使对于多动作工具,AI助手也能获得准确的信号。 - 简单扩展API --使用单个C#属性添加自定义工具、资源、提示和食谱。
需求
- Unity 2022.3或更高版本(包括Unity 6)
- 任何兼容MCP的AI客户端:Claude Code、Claude Desktop、Codex、Cursor或其他
安装
- 打开Unity包管理器(窗口>包管理器)
- 点击 + > 从git URL添加包
- 输入所需版本的URL
最新版本(推荐)
https://github.com/emeryporter/UnityMCP.git?path=/Package
具体版本
附录a #version 标记以固定到释放:
https://github.com/emeryporter/UnityMCP.git?path=/Package#2.2.0
看 发布 对于可用版本。
设置
克劳德代码
claude mcp add unity-mcp --transport http http://localhost:8080/
克劳德桌面版
将此添加到您的Claude Desktop配置文件中:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"unity-mcp": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:8080/"]
}
}
}
保存后重新启动Claude Desktop。
其他MCP客户端(Codex、Cursor等)
Unity MCP公开了一个内置的HTTP服务器 http://localhost:8080/任何支持HTTP传输的MCP兼容客户端都可以直接连接。对于仅支持stdio的客户端,请使用 mcp-remote 如上图所示。
注意:除Claude Code之外的客户端配置尚未经过测试。打开PR!
配置
编辑器窗口
从以下位置打开Unity MCP控制面板 窗口>Unity MCP:
编辑器窗口有四个选项卡:
- 状态 --启动/停止服务器,查看端点URL(使用复制按钮),查看工具/资源/提示/配方计数,配置端口和管理远程访问设置。
- 活动 --MCP请求的实时馈送,包括时间戳、状态指示器和显示参数和响应元数据的可扩展详细信息面板。
- 注册表 --所有注册工具、资源、提示和食谱的可搜索目录。按类别组织,带有注释徽章和可扩展的参数详细信息。
- 检查点 --浏览已保存的检查点,还原或区分场景状态,查看跟踪的资产,并检查存储桶状态。
港口
默认端口为 8080。要更改它,请执行以下操作:
- 停止服务器。
- 在中输入新的端口号 状态 选项卡。
- 点击 应用.
- 启动服务器。
详细日志
切换 详细日志记录 在编辑器窗口中启用Unity控制台中的详细调试输出。有助于解决连接或工具执行问题。
远程访问
启用远程访问,允许AI助手从网络上的其他设备连接:
- 切换远程访问 在 状态 选项卡绑定到所有网络接口(
0.0.0.0). - 需要TLS --Unity MCP自动生成用于安全连接的自签名证书。
- API密钥验证 --带有前缀的密钥
umcp_在首次启用时自动生成,所有远程请求都需要它。 - 复制或重新生成 API键直接从编辑器窗口。
- 端点 变化
https://<LAN_IP>:<port>/当启用远程访问时。 - 证书存储 --存储在
LocalApplicationData/UnityMCP/。如果您的局域网IP发生变化,则自动重新生成。 - 防火墙 --您可能需要在配置的端口上允许传入连接。这是您的责任。
Claude Code远程设置
claude mcp add unity-mcp --transport http --header "Authorization: Bearer <API_KEY>" https://<LAN_IP>:8080/
替换 <API_KEY> 使用您生成的密钥和 <LAN_IP> 使用Unity机器的IP地址。
可用的MCP工具
按类别组织的51个内置工具:
[!提示] 使用
search_tools没有类别概述的论据,或通过query或category缩小结果。使用get_unity_guide用于工作流程指导和工具链配方。
View all 51 built-in tools
场景(8)
| 工具 | 说明 |
|---|---|
create_scene |
在指定路径创建新的空场景 |
load_scene |
按路径或构建索引加载场景 |
save_scene |
保存当前场景(可选)到新路径 |
get_active_scene |
获取有关当前活动场景的信息 |
get_scene_hierarchy |
获取当前场景中游戏对象的层次结构 |
describe_scene |
返回活动场景的叙述性摘要,包括摄影机、照明、关键对象和问题检测 |
manage_checkpoint |
保存、还原、列出或比较场景检查点(action: save, list, restore, diff) |
vision_capture |
以base64格式捕获游戏/场景视图或保存到磁盘,具有可选的目标帧、相机角度和格式控制 |
游戏对象(2)
| 工具 | 说明 |
|---|---|
manage_gameobject |
管理游戏对象(action: create, modify, delete, duplicate, move_relative) |
find_gameobject |
按名称、标签、层、组件、路径或实例ID查找游戏对象 |
组件(1)
| 工具 | 说明 |
|---|---|
manage_component |
管理组件(action: add, remove, set_property, inspect) |
资产(6)
| 工具 | 说明 |
|---|---|
manage_asset |
管理资产(action: create, delete, move, rename, duplicate, import, search, get_info, create_folder) |
manage_prefab |
管理预制操作(action: open_stage, close_stage, save_open_stage, create_from_gameobject) |
manage_material |
管理材料(action: create, get_info, set_property, set_color, assign_to_renderer, set_renderer_color) |
manage_texture |
管理纹理:获取信息、列出、查找、修改导入设置 |
manage_shader |
管理着色器:获取信息、列出、查找、管理关键字 |
manage_scriptable_object |
管理ScriptableObjects:创建、修改、获取、列出 |
VFX(1)
| 工具 | 说明 |
|---|---|
manage_vfx |
管理视觉特效:粒子、线条、轨迹 |
构建与测试(2)
| 工具 | 说明 |
|---|---|
run_build |
管理玩家构建(action: start, get_job) |
run_tests |
运行Unity测试运行程序(action: run, get_job) |
编辑(7)
| 工具 | 说明 |
|---|---|
manage_playmode |
管理播放模式状态(action: enter, exit, pause, step) |
manage_selection |
管理编辑器选择(action: get, set) |
execute_menu_item |
按路径执行Unity编辑器菜单项 |
manage_editor |
管理编辑器状态、标签、图层和工具 |
refresh_unity |
刷新Unity资产数据库,并可选择请求脚本编译 |
focus_editor |
在“场景视图”中构建并选择游戏对象 |
manage_settings |
管理项目设置和编辑器首选项:查找设置文件、检查/设置属性和读/写编辑器首选项 |
控制台和分析(2)
| 工具 | 说明 |
|---|---|
read_console |
通过过滤和分页读取Unity控制台日志条目 |
run_profiler |
控制分析器记录(action: start, stop, get_job) |
UI工具包(6)
| 工具 | 说明 |
|---|---|
uitoolkit_query |
在EditorWindows中查询可视化元素 |
uitoolkit_get_styles |
获取VisualElement的计算USS样式 |
uitoolkit_click |
单击按钮、切换或可单击元素 |
uitoolkit_get_value |
从输入字段获取当前值 |
uitoolkit_set_value |
设置输入字段的值 |
uitoolkit_navigate |
展开/折叠折叠页或选择选项卡 |
指南和诊断(2)
| 工具 | 说明 |
|---|---|
get_unity_guide |
按主题返回Unity工具、约定和工作流配方的降价指南 |
diagnose_scene |
扫描缺少的引用、着色器问题、控制台错误和构建就绪情况 |
出口(1)
| 工具 | 说明 |
|---|---|
export_scene |
将活动场景导出为unitypackage、屏幕截图库或markdown报告 |
食谱(2)
| 工具 | 说明 |
|---|---|
list_recipes |
列出所有可用的场景配方及其描述和参数 |
execute_recipe |
按名称执行场景配方 |
画布用户界面(4)
| 工具 | 说明 |
|---|---|
manage_canvas |
管理Canvas对象:使用CanvasScaler和EventSystem创建、配置、列出或删除Canvas UI |
manage_ui_element |
管理单个uGUI元素:创建、修改、删除、复制、重新排序或添加效果 |
inspect_ui |
检查Canvas UI层次结构:查看元素树、深入检查元素、按类型/名称查找或获取摘要 |
build_ui |
从JSON树描述批量构建完整的Canvas UI,应用模板或批量配置锚点 |
输入(1)
| 工具 | 说明 |
|---|---|
manage_input_actions |
管理输入操作资产:对资产、映射、操作、绑定和复合进行完整的CRUD操作 |
搜索(1)
| 工具 | 说明 |
|---|---|
search_tools |
按名称、描述或类别搜索可用工具 |
公用事业(1)
| 工具 | 说明 |
|---|---|
batch_execute |
在一次调用中使用不同的参数多次执行工具,并带有自动检查点和安全防护栏 |
调试(4)
| 工具 | 说明 |
|---|---|
test_echo |
回显输入消息(连接测试) |
test_add |
添加两个数字(参数处理测试) |
test_unity_info |
获取Unity编辑器的基本信息 |
test_list_scenes |
列出构建设置中的所有场景 |
可用MCP资源
23个内置资源和6个资源模板通过URI模式提供对Unity编辑器状态的只读访问:
View all 29 built-in resources
场景
scene://loaded--当前加载的所有场景及其状态
编辑
editor://state--当前编辑器状态(播放模式、编译、焦点等)editor://selection--编辑器中当前选定的对象editor://windows--打开编辑器窗口及其状态editor://prefab_stage--当前预制件编辑阶段信息editor://active_tool--当前活动的编辑器工具(移动、旋转、缩放等)
项目
project://info--项目路径、名称和Unity版本project://tags--项目标签project://layers--项目层次及其索引project://player_settings--播放器设置,包括图标、分辨率和平台设置project://quality--质量设置和所有质量级别project://physics--物理设置,包括重力、求解器迭代和层碰撞矩阵project://audio--音频设置,包括扬声器模式、DSP缓冲区和采样率project://input--输入系统操作和绑定,或传统输入轴project://rendering--渲染设置,包括渲染管道、环境光和雾
构建和打包
build://settings--构建目标、场景和配置packages://installed--已安装的软件包及其版本
控制台和测试
console://summary--控制台中的错误/警告/信息计数console://errors--包含文件路径和行号的详细编译/运行时错误tests://list--可用单元测试profiler://state--分析器记录状态和配置
菜单
menu://items--可用的Unity编辑器菜单项
用户界面
ui://unitymcp/scene-preview.html--用于内联显示的场景预览小部件HTML
资源模板
这些使用URI参数来查询特定对象:
scene://gameobject/{id}--按实例ID列出的游戏对象详细信息scene://gameobject/{id}/components--游戏对象上的组件列表scene://gameobject/{id}/component/{type}--游戏对象上的特定组件详细信息tests://list/{mode}--按模式筛选的测试(EditMode或PlayMode)animation://controller/{path}--AnimatorController详细信息,包括图层、参数和状态机assets://dependencies/{path}--资产依赖关系——资产使用什么以及使用什么
可用MCP提示
4个用于常见Unity工作流的内置提示模板:
View all 4 built-in prompts
-
read_gameobject--检查游戏对象的变换、组件及其子对象(可选)name(必填)--要检查的游戏对象的名称include_children--是否包括子层次结构(true/false)
-
inspect_prefab--按路径检查预制资产path(必填)-预制资产的路径(例如。,Assets/Prefabs/Player.prefab)
-
modify_component--安全更改组件属性的分步指南target(必填)--目标游戏对象的名称或路径component(必填)-要修改的组件类型(例如。,Rigidbody,BoxCollider)property(必填)-要修改的属性(例如。,mass,isTrigger)
-
setup_scene--为3D、2D或UI设置具有适当默认值的新场景scene_type--场景类型:3d,2d,或ui(默认值:3d)
可用食谱
4个内置场景设置配方:
View all 4 built-in recipes
-
fps_prototype--使用玩家舱、地平面、平行光和眼睛高度的相机创建基本的FPS原型场景ground_size--接地平面尺寸(10–1000,默认值:100)
-
ui_canvas--使用EventSystem和3面板布局(页眉、内容、页脚)创建画布 -
3d_scene_template--使用位于(0,5,-10)的平行光、地平面和摄影机创建基本的3D场景 -
physics_playground--创建一个具有地平面、三个坡道(15°/30°/45°)、五个球体和三个立方体的物理游乐场,所有这些都有刚体
建筑
Unity MCP在Unity编辑器中是完全独立的。本机C插件在后台线程上运行HTTP服务器,并在Unity域重新加载时持续存在,因此即使在Unity重新编译脚本时,AI助手连接也会保持活动状态。不需要外部进程、运行时或sidecar应用程序。
┌─────────────────┐
│ MCP Client │
│ (Claude, etc.) │
└────────┬────────┘
│ HTTP(S) POST (JSON-RPC)
▼
┌─────────────────────────────────────┐
│ Proxy Plugin (C) │
│ - HTTP server on background thread │
│ - Persists across domain reloads │
│ - Buffers request, waits for │
│ response from C# │
└────────┬────────────────────────────┘
│ Polling (EditorApplication.update)
▼
┌─────────────────────────────────────┐
│ Unity C# (main thread) │
│ - Compilation gate: defers │
│ requests while isCompiling │
│ - Routes to MCPServer handlers │
│ - Executes tools, reads resources │
│ │
│ Services: │
│ - CheckpointManager (scene state) │
│ - RecipeRegistry (scene templates) │
│ - UISchema (Canvas UI definitions) │
│ - Response dedup cache (defense) │
└─────────────────────────────────────┘
在脚本重新编译期间,C#编译门将请求消费推迟到域重新加载完成。AI助手看到的是短暂的延迟,而不是断开连接。
扩展Unity MCP
Adding custom tools
有两种方法可以定义工具: 基于动作的工具 用于将相关操作分组到一个工具名称下,以及 单一方法工具 用于独立操作。
基于行动的工具(建议用于相关操作)
地方 [MCPTool] 在静态类和 [MCPAction] 每种行动方法。该框架生成一个统一的JSON模式,其中包含所需的 action 枚举参数。
using UnityEditor;
using UnityMCP.Editor;
using UnityEngine;
[MCPTool("enemy_manager", "Manage enemies in the scene", Category = "Gameplay")]
public static class EnemyManagerTool
{
[MCPAction("spawn", Description = "Spawn an enemy at a position",
DestructiveHint = true)]
public static object Spawn(
[MCPParam("type", "Enemy type", required: true,
Enum = new[] { "goblin", "skeleton", "dragon" })] string type,
[MCPParam("x", "X position", required: true)] float x,
[MCPParam("y", "Y position", required: true)] float y,
[MCPParam("z", "Z position", required: true)] float z)
{
GameObject enemy = new GameObject($"Enemy_{type}");
enemy.transform.position = new Vector3(x, y, z);
return new { instanceID = enemy.GetInstanceID(), type };
}
[MCPAction("list", Description = "List all enemies in the scene",
ReadOnlyHint = true)]
public static object List()
{
var enemies = GameObject.FindGameObjectsWithTag("Enemy");
return new { count = enemies.Length };
}
[MCPAction("despawn", Description = "Remove an enemy from the scene",
DestructiveHint = true)]
public static object Despawn(
[MCPParam("instance_id", "Instance ID of the enemy to remove",
required: true)] int instanceId)
{
var target = EditorUtility.InstanceIDToObject(instanceId) as GameObject;
if (target == null) return new { success = false, error = "Enemy not found." };
Object.DestroyImmediate(target);
return new { success = true };
}
}
基于动作的工具的注释解析:
destructiveHint = true如果 任何 行动已经DestructiveHint = truereadOnlyHint = true只有当 全部 行动已经ReadOnlyHint = true
服务器使用每个动作的元数据来告诉AI助手哪些具体动作需要检查点才能继续,而不是标记整个工具。
单方法工具(用于独立操作)
地方 [MCPTool] 直接在静态方法上:
using UnityMCP.Editor;
using UnityEngine;
public static class MyCustomTools
{
[MCPTool("hello_world", "Says hello to the specified name")]
public static string SayHello(
[MCPParam("name", "Name to greet", required: true)] string name)
{
return $"Hello, {name}!";
}
[MCPTool("spawn_enemy", "Spawn an enemy at a position with difficulty scaling",
Category = "Gameplay", DestructiveHint = true)]
public static object SpawnEnemy(
[MCPParam("enemy_type", "Type of enemy to spawn", required: true,
Enum = new[] { "goblin", "skeleton", "dragon" })] string enemyType,
[MCPParam("x", "X position", required: true)] float x,
[MCPParam("y", "Y position", required: true)] float y,
[MCPParam("z", "Z position", required: true)] float z,
[MCPParam("difficulty", "Difficulty multiplier (1–10)",
Minimum = 1, Maximum = 10)] float difficulty = 5)
{
GameObject enemy = new GameObject($"Enemy_{enemyType}");
enemy.transform.position = new Vector3(x, y, z);
return new
{
instanceID = enemy.GetInstanceID(),
type = enemyType,
difficulty
};
}
}
域重新加载时会自动发现工具。无需注册。
工具注释
在上设置注释 [MCPTool] 对于单方法工具,或 [MCPAction] 基于动作的工具上的每个动作的准确性。
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
Category |
string |
"Uncategorized" |
组中的相关工具 search_tools 结果(设置 [MCPTool]) |
ReadOnlyHint |
bool |
false |
操作不修改任何状态 |
DestructiveHint |
bool |
false |
操作可能会执行不可逆的更改 |
IdempotentHint |
bool |
false |
同样的论点总是产生同样的结果 |
OpenWorldHint |
bool |
false |
操作与Unity之外的系统交互 |
Title |
string |
null |
人类可读的显示标题(设置 [MCPTool]) |
参数约束
约束包含在发送给AI助手的JSON模式中:
| 属性 | 类型 | 描述 |
|---|---|---|
Enum |
string[] |
字符串参数的有效值 |
Minimum |
double |
数值参数的最小值 |
Maximum |
double |
数值参数的最大值 |
Adding custom resources
资源通过URI模式向AI助手公开只读数据。使用 [MCPResource]:
using UnityMCP.Editor;
using UnityEngine;
public static class MyCustomResources
{
[MCPResource("unity://player/stats", "Current player statistics")]
public static object GetPlayerStats()
{
var player = GameObject.Find("Player");
if (player == null)
return new { error = "Player not found" };
return new
{
position = player.transform.position,
health = player.GetComponent<Health>()?.CurrentHealth ?? 0,
isGrounded = player.GetComponent<CharacterController>()?.isGrounded ?? false
};
}
}
资源通过以下方式读取 resources/read 使用它们的URI(例如。, unity://player/stats).它们在域重新加载时自动被发现。
Adding custom prompts
提示为AI助手提供可重用的工作流模板。使用 [MCPPrompt]:
using System.Collections.Generic;
using UnityMCP.Editor;
using UnityMCP.Editor.Core;
public static class MyCustomPrompts
{
[MCPPrompt("debug_gameobject", "Debug a GameObject by inspecting its state")]
public static PromptResult DebugGameObject(
[MCPParam("name", "Name of the GameObject to debug", required: true)] string name,
[MCPParam("verbose", "Include full component details (true/false)")] string verbose = "false")
{
bool isVerbose = verbose?.ToLower() == "true";
string instructions = $@"Debug the GameObject ""{name}"" using these steps:
1. Use `find_gameobject` with search_term=""{name}"" to locate it
2. Use `manage_component` with action=""inspect"" to check each component";
if (isVerbose)
{
instructions += $@"
3. Use `read_console` with filter=""{name}"" to check for related log messages";
}
return new PromptResult
{
description = $"Debug instructions for '{name}'",
messages = new List<PromptMessage>
{
new PromptMessage
{
role = "user",
content = new PromptMessageContent
{
type = "text",
text = instructions
}
}
}
};
}
}
Adding custom recipes
食谱是可重用的场景设置模板,通过以下方式调用 execute_recipe.使用 [MCPRecipe] 关于静态方法:
using UnityMCP.Editor;
public static class MyRecipes
{
[MCPRecipe("my_scene_setup", "Creates a custom scene layout")]
public static object MySceneSetup(
[MCPParam("size", "World size", Minimum = 10, Maximum = 500)] float size = 50)
{
// Create your scene objects here...
return new { success = true, summary = "Scene created" };
}
}
重新加载域时会自动发现食谱,并显示在 list_recipes 输出。
许可证
GPLv3--有关详细信息,请参阅LICENSE文件。