Unity AI助手集成工具

Unity原生MCP服务器,为AI驱动的游戏开发提供支持,无需外部运行时即可直接连接Unity Editor与AI助手。

  • by emeryporter
  • C#
  • 本地部署
  • 10 星标
  • 更新于
在 GitHub 查看 Bluepuff71/UnityMCP

使用说明

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或其他

安装

  1. 打开Unity包管理器(窗口>包管理器)
  2. 点击 + > 从git URL添加包
  3. 输入所需版本的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。要更改它,请执行以下操作:

  1. 停止服务器。
  2. 在中输入新的端口号 状态 选项卡。
  3. 点击 应用.
  4. 启动服务器。

详细日志

切换 详细日志记录 在编辑器窗口中启用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 = true
  • readOnlyHint = 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文件。