🎮 Unity MCP夏普

Unity编辑器模型上下文协议的C#实现

Unity MCP Sharp是一个生产就绪的MCP服务器，使AI助手（Claude、Cursor等）能够直接与Unity编辑器交互。用。NET 9.0和官方MCP C#SDK，它为游戏开发自动化提供了34个强大的工具，包括场景操纵、游戏对象创建、预制件管理、资产管理和实时游戏模式控制。

![Build Server](https://github.com/Abbabon/unity-mcp-sharp/actions/workflows/build-server.yml) ](https://github.com/Abbabon/unity-mcp-sharp/actions/workflows/publish-docker.yml) ![CodeQL](https://github.com/Abbabon/unity-mcp-sharp/actions/workflows/codeql.yml) ![License: MIT](https://opensource.org/licenses/MIT) ](https://github.com/Abbabon/unity-mcp-sharp/releases) ![Maintenance](https://github.com/Abbabon/unity-mcp-sharp/graphs/commit-activity) ![openupm](https://openupm.com/packages/com.mezookan.unity-mcp-sharp/) ](https://openupm.com/packages/com.mezookan.unity-mcp-sharp/) ![All Contributors](#contributors) Top Language

______________________________________________________________________

______________________________________________________________________

✨ 特性

🔌 WebSocket Communication (JSON-RPC 2.0)

与Unity Editor进行实时双向通信
可扩展的命令/响应模式
支持Unity操作和查询

🛠️ 28 MCP Tools + 7 MCP Resources

类别	工具和资源
资源（只读）	项目信息、控制台日志、编译状态、播放模式、活动场景、场景对象、所有场景
多编辑器	列出已连接的编辑器，为会话选择编辑器
控制台和编译	触发编译，刷新资产
游戏对象	创建、查找、批量创建、添加组件、设置组件字段、列出场景对象
场景	列出、打开、关闭、保存、获取/设置活动场景
资产	创建脚本，创建具有复杂结构的资产（ScriptableObjects、Materials等）
播放模式	进入、退出、获取播放模式状态
系统	以编程方式运行任何Unity菜单项

🔀 Multi-Editor Support (v0.5.0+)

多个Unity编辑器：将多个Unity Editor实例连接到单个MCP服务器
每次会话选择：每个MCP客户端（LLM会话）可以独立选择和使用不同的编辑器
智能自动选择：单个编辑器场景无需手动选择即可无缝工作
持续不断地进行重新编译：编辑器选择保留Unity脚本编译重新连接
元数据：每个编辑器报告项目名称、场景、机器、进程ID、Unity版本

🤖 Optimized for LLM Interaction

✅ 所有工具都会返回确认消息以获得可靠的反馈
🔗 工具描述包括链接操作的交叉引用
⚠️ 明确记录副作用和警告
📝 丰富的退货描述有助于LLM理解回复
📊 工具配置文件：使用Minimal（12个工具）、Standard（20个）或Full（28个）减少令牌使用

📦 Unity Package (OpenUPM compatible)

🎨 基于UIToolkit的仪表板，具有状态监控功能
👁️ 带有操作跟踪的视觉反馈系统
🐳 Docker容器生命周期管理
🔄 自动连接和自动启动功能
🎯 自动对焦：在接收MCP操作时自动将Unity置于前台
⚙️ 通过ScriptableObject进行配置

🐳 Dockerized Server

用。NET 9.0和ASP。NET核心
发布到GitHub容器注册表（ghcr.io）
多平台支持（linux/amd64、linux/arm64）
带有GitHub操作的完整CI/CD管道

______________________________________________________________________

🏗️ 建筑

基本流程

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
│   AI Assistant  │         │   Unity Editor   │         │  Unity Package  │
│  (IDE/LLM)      │◄────────┤                  │◄────────┤  (OpenUPM)      │
└────────┬────────┘  MCP    │                  │ Editor  └────────┬────────┘
         │         (HTTP)   │                  │  API             │
         │                  └──────────────────┘                  │
         │                                                        │
         │                                                        │
         └────────────────┐                    ┌─────────────────┘
                          │                    │
                          ▼                    ▼ WebSocket
                    ┌──────────────────────────────┐
                    │   Unity MCP Server           │
                    │   (Docker Container)         │
                    │   ┌────────────────────┐     │
                    │   │  ASP.NET Core      │     │
                    │   │  - HTTP Endpoint   │     │
                    │   │  - WebSocket       │     │
                    │   │  - JSON-RPC 2.0    │     │
                    │   └────────────────────┘     │
                    └──────────────────────────────┘

多编辑器架构（v0.5.0+）

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ MCP Session  │  │ MCP Session  │  │ MCP Session  │
│     A        │  │     B        │  │     C        │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └────────┬────────┴────────┬────────┘
                │                 │
                ▼                 ▼
          ┌─────────────────────────────┐
          │  MCP Server                 │
          │  ┌───────────────────────┐  │
          │  │ EditorSessionManager  │  │  Session → Editor Mapping
          │  │ McpSessionMiddleware  │  │  AsyncLocal Context
          │  └───────────────────────┘  │
          └─────────────────────────────┘
                │         │         │
       ┌────────┘         │         └────────┐
       ▼                  ▼                  ▼
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│Unity Editor 1│   │Unity Editor 2│   │Unity Editor 3│
│  ProjectA    │   │  ProjectB    │   │  ProjectC    │
│  SceneX      │   │  SceneY      │   │  SceneZ      │
└──────────────┘   └──────────────┘   └──────────────┘

______________________________________________________________________

🚀 快速开始

先决条件

统一 2021.3或更晚
Docker桌面 已安装并正在运行
.NET 9.0 SDK （仅用于服务器开发）

三步设置

安装软件包 （参见安装在......下面
打开安装向导 在Unity中： Tools → Unity MCP Server → Setup Wizard
启动并连接 通过仪表板： Tools → Unity MCP Server → Dashboard

✅ 完成！你已经准备好使用Unity的AI助手了。

______________________________________________________________________

📦 安装

Option 1: OpenUPM (Recommended) ⭐

openupm add com.mezookan.unity-mcp-sharp

Option 2: Git URL

打开Unity包管理器
点击 + → “从git URL添加包…”
输入： https://github.com/Abbabon/unity-mcp-sharp.git

Option 3: Manual Installation

添加到 Packages/manifest.json:

{
  "dependencies": {
    "com.mezookan.unity-mcp-sharp": "https://github.com/Abbabon/unity-mcp-sharp.git"
  }
}

首次设置

Click to expand setup steps

安装Docker桌面 （如果尚未安装）

- 下载自 - 启动Docker桌面

打开安装向导

- 在Unity中： Tools → Unity MCP Server → Setup Wizard - 按照屏幕上的说明进行操作

启动服务器

- 首选 Tools → Unity MCP Server → Dashboard - 点击 “启动服务器” （首次运行时下载Docker镜像） - 点击 “连接” 建立WebSocket连接

验证连接

- 仪表板显示“已连接”✓“绿色 - 控制台日志：“Unity MCP服务器已成功连接”

______________________________________________________________________

🤖 使用AI助手

Claude Code (CLI)

添加到您的项目 .mcp.json 项目根目录中的文件：

{
  "mcpServers": {
    "unity": {
      "url": "http://localhost:3727/mcp"
    }
  }
}

或在全球范围内添加 ~/.claude.json:

{
  "mcpServers": {
    "unity": {
      "url": "http://localhost:3727/mcp"
    }
  }
}

提示： 添加配置后，重新启动Claude Code或使用 /mcp 以验证服务器是否已连接。

VS Code / GitHub Copilot

添加到 .vscode/settings.json:

{
  "mcpServers": {
    "unity": {
      "url": "http://localhost:3727/mcp",
      "transport": "sse"
    }
  }
}

Cursor IDE

添加到 ~/.cursor/config.json:

{
  "mcpServers": {
    "unity": {
      "url": "http://localhost:3727/mcp",
      "transport": "sse"
    }
  }
}

Claude Desktop

添加到您的Claude Desktop MCP配置中：

{
  "mcpServers": {
    "unity": {
      "url": "http://localhost:3727/mcp",
      "transport": "sse"
    }
  }
}

______________________________________________________________________

🛠️ 可用的MCP工具和资源

所有工具都是为最佳LLM交互而设计的 带有确认消息、工具链提示和副作用警告。

📚 MCP Resources (7 resources)

v0.4中的新功能： 资源是只读的、由应用程序控制的数据源，每次访问时都会提供新的数据。它们通过将读取操作与基于动作的工具分离来减少LLM的认知负荷。

`unity://project/info`

Unity项目元数据，包括名称、版本、活动场景、路径和编辑器状态。

退货： 项目信息，包括名称、Unity版本、活动场景、数据路径、播放/暂停状态

💡 提示： 在开始项目工作时，首先使用此方法来了解环境。

🔄 更新： 当场景改变或播放模式改变时自动

______________________________________________________________________

`unity://console/logs`

Unity编辑器最近的控制台日志（错误、警告、调试日志）。

退货： 带有类型、消息和堆栈跟踪的控制台日志

💡 提示： 在创建脚本、进入播放模式或编译失败后检查此项。

🔄 更新： 新日志消息出现时自动

______________________________________________________________________

`unity://compilation/status`

当前编译状态和上次编译结果。

退货： 编译状态（空闲/编译）和成功/失败状态

🔗 相关： unity_trigger_script_compilation

🔄 更新： 编译开始或完成时自动执行

______________________________________________________________________

`unity://editor/playmode`

Unity编辑器的当前播放模式状态。

退货： 播放模式状态（播放、暂停或停止）

🔗 相关： unity_enter_play_mode, unity_exit_play_mode

🔄 更新： 播放模式更改时自动

______________________________________________________________________

`unity://scenes/active`

有关当前活动Unity场景的信息。

退货： 场景名称、路径、isDirty状态、根游戏对象计数、加载状态

💡 提示： 如果isDirty为真，请使用 unity_save_scene 以保存更改。

🔄 更新： 当活动场景更改或加载场景时自动

______________________________________________________________________

`unity://scenes/active/objects`

活动场景的完整游戏对象层次结构。

退货： 带有活动/非活动状态指示器的分层列表

🔗 相关： unity_find_game_object, unity_create_game_object

🔄 更新： 场景更改时自动

______________________________________________________________________

`unity://scenes/all`

项目中所有.unity场景文件的列表。

退货： 相对于项目根的场景路径列表

🔗 相关： unity_open_scene, unity_get_active_scene

🔄 更新： 资产数据库刷新时

🔍 System & Compilation (1 tool)

`unity_trigger_script_compilation`

强制Unity重新编译所有C#脚本。

退货： 确认编译已触发

⚠️ 注： Unity在编译期间暂时断开连接。使用 unity://compilation/status 资源验证成功后。

🎮 GameObjects (7 tools)

`unity_create_game_object`

在当前活动场景中创建新的游戏对象。

参数：

name （字符串，必填）：游戏对象名称
x, y, z （浮点数，默认值：0）：世界位置
components （字符串，可选）：逗号分隔的组件（例如，“刚体，BoxCollider”）
parent （字符串，可选）：父游戏对象名称

退货： 确认名称、职位、组件和层次结构位置

📌 例子： 使用刚体和胶囊对撞机在位置（0,1,0）创建一个“玩家”

🔗 相关： unity_find_game_object, unity_add_component_to_object

______________________________________________________________________

`unity_find_game_object`

按名称、标签或包含详细信息的路径查找游戏对象。

参数：

name （字符串，必填）：游戏对象名称
searchBy （字符串，默认值：“name”）：搜索模式：“名称”、“标签”或“路径”

退货： 位置、旋转、比例、活动状态和所有连接的组件

🔗 相关： unity_list_scene_objects, unity_add_component_to_object

______________________________________________________________________

`unity_add_component_to_object`

向现有游戏对象添加组件。

参数：

gameObjectName （字符串，必填）：目标游戏对象
componentType （字符串，必填）：组件类型（例如，“刚体”、“BoxCollider”、自定义脚本）

退货： 确认已添加组件

💡 提示： 使用 unity_find_game_object 首先验证游戏对象是否存在。

______________________________________________________________________

`unity_set_component_field`

在附着到游戏对象的组件上设置字段或属性值。

参数：

gameObjectName （string，必填）：包含组件的游戏对象的名称
componentType （字符串，必填）：组件的类型（例如，“Transform”、“Rigidbody”、自定义脚本）
fieldName （字符串，必填）：要设置的字段或属性名称（例如，“enabled”、“mass”、“config”）
value （字符串，必填）：要设置的值（图元、资源路径或游戏对象名称）
valueType （字符串，默认值：“string”）：值类型：“字符串”、“int”、“float”、“bool”、“资产”、“gameObject”

退货： 确认字段已设置

📌 例子： 设置ScriptableObject引用： valueType: "asset", value: "Assets/Config/MyConfig.asset"

🔗 相关： unity_find_game_object, unity_add_component_to_object

______________________________________________________________________

`unity_list_scene_objects`

获取活动场景的完整游戏对象层次结构。

退货： 带有活动/非活动状态指示器的分层列表

🔗 相关： unity_find_game_object, unity_create_game_object

______________________________________________________________________

`unity_batch_create_game_objects`

在单个操作中创建多个游戏对象（比逐一创建更有效）。

参数：

gameObjectsJson （string，必填）：游戏对象规格的JSON数组

退货： 确认批创建已启动

______________________________________________________________________

`unity_create_game_object_in_scene`

在特定场景（不一定是活动场景）中创建游戏对象。

参数：

scenePath （字符串，必填）：场景路径（例如“Scenes/Level1.unity”）
name, x, y, z, components, parent：与 unity_create_game_object

退货： 确认场景路径、名称和位置

⚠️ 注： 若场景未加载，它将首先以相加方式打开。

📦 Prefabs (6 tools)

`unity_create_prefab`

从场景中的现有游戏对象创建预制资源。

参数：

gameObjectName （string，必填）：要转换为预制件的游戏对象的名称
assetFolderPath （字符串，必填）：资源文件夹中的路径（例如，“预制件”、“预制件/角色”）
prefabName （字符串，可选）：预制文件的名称（默认为游戏对象名称）
createVariant （bool，default:false）：创建一个prefab变量而不是常规prefab

退货： 使用预制路径和源游戏对象名称进行确认

📌 例子： 在资源/预制件/角色/Player.prefab中将“玩家”游戏对象转换为预制件

🔗 相关： unity_find_game_object, unity_get_prefab_info, unity_instantiate_prefab

💡 提示： 使用 unity_find_game_object 首先验证游戏对象是否存在。如果文件夹不存在，将创建该文件夹。

______________________________________________________________________

`unity_instantiate_prefab`

将预制件实例化（生成）到当前活动场景中。

参数：

prefabPath （字符串，必填）：相对于“资源”文件夹的预制件路径（例如，“预制件/Character.prefab”）
x, y, z （浮点数，默认值：0）：世界位置
rotationX, rotationY, rotationZ （浮动，默认值：0）：Euler角度旋转
scaleX, scaleY, scaleZ （浮点数，默认值：1）：缩放倍数
parent （字符串，可选）：父游戏对象名称
instanceName （字符串，可选）：生成实例的自定义名称

退货： 使用实例名称、位置和预制源路径进行确认

📌 例子： 以90°Y旋转在（10,0,5）处预置“敌人”

🔗 相关： unity_find_game_object, unity_list_scene_objects

💡 提示： 实例保持与预制件资源的连接，并在修改预制件时接收更新。

______________________________________________________________________

`unity_get_prefab_info`

获取有关游戏对象预制件状态和关系的详细信息。

参数：

gameObjectNameOrPath （字符串，必填）：场景中的游戏对象名称或预制资源路径

退货： 带有前缀信息的JSON对象：

isPrefabAsset：这是预制资产文件吗
isPrefabInstance：这是场景中的预制实例吗
isPrefabVariant这是预制的变体吗
assetPath：预制资产的路径
isModified：实例是否有覆盖
prefabInstanceStatus：与源预制件的连接状态

📌 例子： 检查“Player”是否是经过修改的预制实例

🔗 相关： unity_create_prefab, unity_open_prefab

💡 提示： 以前用这个 unity_open_prefab 了解前言关系。

______________________________________________________________________

`unity_open_prefab`

在预制模式（隔离模式）下打开预制资源进行编辑。

参数：

prefabPath （字符串，必填）：相对于Assets文件夹的预制件路径
inContext （bool，默认值：false）：在上下文模式下打开（显示场景上下文）与隔离模式

退货： 使用预制路径和模式信息进行确认

📌 例子： 在隔离模式下打开“资源/预制件/敌人.预制件”进行编辑

🔗 相关： unity_save_prefab, unity_close_prefab_stage

⚠️ 重要提示： 一次只能在预制模式下打开一个预制件。先关闭当前预制件，再打开另一个预制件。

💡 提示： 使用隔离模式进行聚焦编辑，使用上下文模式查看预制件在场景中的适应程度。

______________________________________________________________________

`unity_save_prefab`

保存对当前在预制模式下打开的预制件所做的更改。

参数：

prefabPath （字符串，可选）：要保存的特定预制件（如果未提供，则保存当前打开的预制件）

退货： 确认已保存的内容

📌 例子： 保存对当前打开的预制件的修改

🔗 相关： unity_open_prefab, unity_close_prefab_stage

⚠️ 重要提示： 在预制模式下进行更改后，始终调用此命令以确保更改不会丢失。

💡 提示： 还可以将预制实例中的替代应用回源预制资源。

______________________________________________________________________

`unity_close_prefab_stage`

关闭当前打开的预制模式并返回场景编辑。

参数：

saveBeforeClosing （bool，默认值：true）：关闭前保存前言（false丢弃未保存的更改）

退货： 确认预制阶段已结束

📌 例子： 关闭预制编辑模式并保存更改

🔗 相关： unity_open_prefab, unity_save_prefab

⚠️ 重要提示： 如果发生以下情况，未保存的更改将丢失 saveBeforeClosing 是假的。打开另一个预制件之前必须关闭。

💡 提示： 集 saveBeforeClosing 设为true（默认）以避免丢失工作。

🎬 Scenes (6 tools)

`unity_list_scenes`

列出项目中的所有.unity场景文件。

退货： 相对于项目根的场景路径列表

🔗 相关： unity_open_scene, unity_get_active_scene

______________________________________________________________________

`unity_get_active_scene`

获取有关当前活动场景的信息。

退货： 场景名称、路径、isDirty状态、根游戏对象计数、加载状态

💡 提示： 使用 unity_save_scene 如果isDirty为true，则保存更改。

______________________________________________________________________

`unity_open_scene`

按路径打开Unity场景。

参数：

scenePath （字符串，必填）：相对于Assets文件夹的路径
additive （bool，默认值：false）：如果为true，则保持其他场景打开

退货： 场景路径和模式确认（单/加）

🔗 相关： unity_list_scenes, unity_get_active_scene

______________________________________________________________________

`unity_close_scene`

关闭特定场景（仅适用于打开多个场景的情况）。

参数：

sceneIdentifier （字符串，必填）：场景名称或路径

退货： 确认现场已关闭

⚠️ 注： 无法关闭最后一个打开的场景。

______________________________________________________________________

`unity_save_scene`

保存活动场景或特定场景。

参数：

scenePath （字符串，可选）：要保存的特定场景（空=活动）
saveAll （bool，默认值：false）：保存所有打开的场景

退货： 确认保存了哪些场景

⚠️ 重要提示： 更改后务必保存，否则将丢失！

______________________________________________________________________

`unity_set_active_scene`

设置哪个场景处于活动状态（创建新游戏对象的位置）。

参数：

sceneIdentifier （字符串，必填）：场景名称或路径

退货： 确认场景现在处于活动状态

⚠️ 注： 仅在打开多个场景时有效。

📁 Assets & Scripts (3 tools)

`unity_create_script`

创建一个新的C#MonoBehaviour脚本文件。

参数：

scriptName （字符串，必填）：脚本名称（不带.cs）
folderPath （字符串，必填）：资源内的路径（例如“脚本/播放器”）
scriptContent （string，必填）：完整的C#类代码

退货： 确认文件路径和重新编译通知

🔗 相关： unity_get_compilation_status, unity_get_console_logs

______________________________________________________________________

`unity_create_asset`

使用SerializedObject API创建支持复杂嵌套结构的任何类型的Unity资产。

参数：

assetName （字符串，必填）：资产名称（不带扩展名）
folderPath （字符串，必填）：资产内的路径
assetTypeName （字符串，必填）：完整类型名称（例如，“UnityEngine.Material”，自定义ScriptableObject）
propertiesJson （字符串，可选）：要设置的JSON属性（支持嵌套对象、数组、列表）

退货： 确认资产名称、类型和路径

✨ v0.4中的新功能： 对复杂嵌套结构的序列化对象支持增强！

📌 示例属性：

材料： {"shader":"Standard","color":"#FF0000"}
纹理2D： {"width":256,"height":256}
带嵌套列表的ScriptableObject：

{
  "primitives": [
    {
      "primitiveType": 0,
      "position": {"x": 0, "y": 0, "z": 0},
      "color": {"r": 1, "g": 0, "b": 0, "a": 1},
      "scale": {"x": 1, "y": 1, "z": 1}
    }
  ]
}

🎯 支持的Unity类型： 矢量3、矢量2、颜色、四元数、边界、矩形、资源引用等等！

🔗 相关： unity_refresh_assets

______________________________________________________________________

`unity_refresh_assets`

刷新Unity资产数据库以检测文件更改。

退货： 确认刷新已启动

💡 使用后： 批处理文件操作或未自动检测到更改时

⚠️ 注： 对于大型项目，可能需要几秒钟的时间。使用 unity_get_compilation_status 检查重新编译是否完成。

▶️ Play Mode (3 tools)

`unity_enter_play_mode`

进入Unity游戏模式（开始运行游戏）。

退货： 带有重要警告的确认消息

⚠️ 重要： 在播放模式下所做的更改不会被保存！退出时，创建的游戏对象将被销毁。

🔗 相关： unity_get_play_mode_state, unity_exit_play_mode

______________________________________________________________________

`unity_exit_play_mode`

退出Unity游戏模式（停止运行游戏）。

退货： 确认已退出播放模式

⚠️ 注： 在播放模式下所做的所有更改都将恢复。

______________________________________________________________________

`unity_get_play_mode_state`

获取当前播放模式状态。

退货： 当前状态（播放、暂停或停止）

🔗 相关： unity_enter_play_mode, unity_exit_play_mode

⚙️ System Utilities (2 tools)

`unity_run_menu_item`

按路径执行任何Unity编辑器菜单项。

参数：

menuPath （字符串，必填）：完整菜单路径（例如，“游戏对象/创建空”、“编辑/撤消”）

退货： 确认菜单项已执行

💡 用作： 专用工具未涵盖的操作回退

📌 示例：

"GameObject/Create Empty"
"Edit/Undo"
"Assets/Refresh"

______________________________________________________________________

`unity_bring_editor_to_foreground`

将Unity编辑器窗口置于前台。

退货： 确认前台请求已发送

💡 注： 当启用“自动带到前台”设置时（默认：打开），大多数MCP操作会自动将Unity带到前台。如果禁用了自动聚焦，或者在执行一系列操作之前需要确保Unity可见，请明确使用此工具。

🔧 平台支持： Windows（SetForegroundWindow）和macOS（NSApplication.activate）。Linux目前不支持自动对焦。

______________________________________________________________________

🐳 Docker 镜像

Pull from GitHub Container Registry

docker pull ghcr.io/abbabon/unity-mcp-server:latest

Run Manually

docker run -d \
  --name unity-mcp-server \
  -p 3727:3727 \
  --restart unless-stopped \
  ghcr.io/abbabon/unity-mcp-server:latest

Available Tags

标签	描述
`latest`	主分支的最新稳定版本
`v..*`	特定版本标签（例如。， `v0.3.2`)
`main`	主分支的最新构建

______________________________________________________________________

💻 发展

Development Scripts

该项目包括便利脚本 Scripts~/:

# Build server + Docker image
./Scripts~/rebuild.sh

# Start MCP server container
./Scripts~/start-mcp-server.sh

# Run smoke tests
./Scripts~/test.sh

Server Development

cd Server~

# Restore dependencies
dotnet restore

# Build
dotnet build

# Run locally
dotnet run

# Build Docker image (or use ./Scripts~/rebuild.sh)
docker build -t unity-mcp-server:test .

# Run with docker-compose
docker-compose up

Unity Package Development

该软件包的结构为Unity UPM软件包：

.
├── Runtime/              # Runtime scripts (MCPClient, MCPServerManager)
├── Editor/               # Editor scripts (Dashboard, Integration, Menu Items)
├── Documentation~/       # User documentation (excluded from package)
├── Scripts~/             # Development scripts (excluded from package)
├── Server~/              # MCP server (excluded from package)
├── TestProject~/         # Test Unity project (excluded from package)
└── package.json          # UPM manifest

注：目录与 ~/ Unity包导入中不包括后缀。

______________________________________________________________________

⚙️ 配置

通过访问配置 Tools → Unity MCP Server → Create MCP Configuration 或通过仪表板。

Available Settings

设置	默认值	说明
服务器URL	`ws://localhost:3727/ws`	WebSocket连接URL
Docker镜像	`ghcr.io/abbabon/unity-mcp-server:latest`	要使用的Docker镜像
自动连接	`true`	启动时自动连接
自动启动	`false`	自动启动容器
自动带到前台	`true`	当MCP操作需要时，自动将Unity置于前台
工具配置文件	`Standard`	控制哪些MCP工具暴露在外：最小（12）、标准（20）、完全（28）
重试尝试	`3`	连接重试尝试
重试延迟	`2000ms`	重试之间的延迟
详细日志记录	`false`	启用详细日志
最大日志缓冲区	`1000`	要保留的最大日志条目数

📊 Tool Profiles (Token Optimization)

工具配置文件通过仅公开所需的MCP工具来帮助减少令牌使用。通过仪表板设置选项卡进行配置。

配置文件	工具	描述
最小化	12	基本工作流程的核心工具（创建、查询、播放模式）
标准	20	常用工具，包括组件操作和资产创建
满的	28	所有工具，包括批处理操作和多编辑器功能

最小配置文件包括：

场景查询： unity_get_project_info, unity_list_scene_objects, unity_find_game_object
游戏对象： unity_create_game_object, unity_delete_game_object
脚本： unity_create_script, unity_get_compilation_status, unity_get_console_logs
播放模式： unity_enter_play_mode, unity_exit_play_mode
场景： unity_open_scene, unity_save_scene

标准配置文件添加了：

组件操作： unity_add_component_to_object, unity_set_component_field
资产： unity_create_asset, unity_refresh_assets, unity_trigger_script_compilation
场景信息： unity_get_active_scene, unity_list_scenes, unity_get_play_mode_state

完整配置文件添加：

批量操作： unity_batch_create_game_objects
多场景： unity_create_game_object_in_scene, unity_close_scene, unity_set_active_scene
多编辑器： unity_list_editors, unity_select_editor
系统： unity_run_menu_item, unity_bring_editor_to_foreground

要应用配置文件更改，请执行以下操作：

在Unity仪表板（设置选项卡）中更改配置文件并保存
在Cursor中：禁用MCP服务器，然后重新启用它（或重新启动Cursor）

这是必需的，因为Cursor会缓存工具列表。配置文件按项目存储在 MCPConfiguration.asset.

______________________________________________________________________

🔧 故障排除

❌ Docker not found

解决方案： 安装Docker Desktop并确保其正在运行。

下载自

❌ Connection refused

可能的原因：

Docker容器未运行 → 从仪表板启动
端口3727已在使用中 → 更改配置中的端口
防火墙阻止连接 → 在防火墙设置中允许Docker

❌ Container fails to start

检查日志：

docker logs unity-mcp-server

或使用日志 Unity MCP仪表板中的选项卡。

❌ "Image not found" error

软件包将在首次启动时自动拉取图像。如果失败：

# Manually pull the image
docker pull ghcr.io/abbabon/unity-mcp-server:latest

❌ macOS: "Docker command not found"

解决方案： 该软件包会自动检查macOS上的常见Docker路径：

/usr/local/bin/docker （Docker桌面）
/opt/homebrew/bin/docker （苹果硅上的自制）
/usr/bin/docker （标准位置）

如果仍然找不到，请确保Docker Desktop已安装并正在运行。

⚠️ Unity 6+: "Package signature warning"

从Unity 6.3开始，包管理器显示未签名包的签名警告。这只是信息性的，软件包仍然可以正常工作。

选项：

下载签名 .tgz 从（如果可用）
通过OpenUPM安装（警告仅是装饰性的）
看包签名指南详情

有关更多故障排除帮助，请参阅故障排除指南.

______________________________________________________________________

🤝 贡献

欢迎投稿！拜托：

克隆该仓库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

CI/CD Pipeline

该项目包括全面的GitHub Actions工作流：

构建服务器 -构建并测试。NET服务器上的每个推送/PR
发布Docker -将多拱形图像发布到主分支上的ghcr.io
发布OpenUPM -创建GitHub版本并在版本标签上指导OpenUPM发布

创建发布

# Update version in package.json
# Commit changes
git add package.json
git commit -m "Bump version to 1.0.0"

# Create and push tag
git tag v1.0.0
git push origin main --tags

这将触发完整的CI/CD管道。

______________________________________________________________________

📄 许可证

MIT许可证-请参阅许可证文件以获取详细信息。

______________________________________________________________________

🔗 链接

📚 文档

🌐 资源

问题：
模型上下文协议： 模型上下文协议.io
Docker注册表： ghcr.io/abbabon/unity-mcp服务器

______________________________________________________________________

📊 项目统计

语言细分

Language Stats

贡献者

感谢这些为这个项目做出贡献的优秀人士！

AmitN

______________________________________________________________________

🙏 谢谢

内置：

______________________________________________________________________

由...制作❤️ Unity和AI社区

⭐ 明星历史

![Star History Chart](https://www.star-history.com/#Abbabon/unity-mcp-sharp&type=date&legend=top-left)

Unity MCP Sharp

快速接入

详细介绍

🎮 Unity MCP夏普

📋 目录

✨ 特性

🏗️ 建筑

基本流程

多编辑器架构（v0.5.0+）

🚀 快速开始

先决条件

三步设置

📦 安装

首次设置

🤖 使用AI助手

🛠️ 可用的MCP工具和资源

unity://project/info

unity://console/logs

unity://compilation/status

unity://editor/playmode

unity://scenes/active

unity://scenes/active/objects

unity://scenes/all

unity_trigger_script_compilation

unity_create_game_object

unity_find_game_object

unity_add_component_to_object

unity_set_component_field

unity_list_scene_objects

unity_batch_create_game_objects

unity_create_game_object_in_scene

unity_create_prefab

unity_instantiate_prefab

unity_get_prefab_info

unity_open_prefab

unity_save_prefab

unity_close_prefab_stage

unity_list_scenes

unity_get_active_scene

unity_open_scene

unity_close_scene

unity_save_scene

unity_set_active_scene

unity_create_script

unity_create_asset

unity_refresh_assets

unity_enter_play_mode

unity_exit_play_mode

unity_get_play_mode_state

unity_run_menu_item

unity_bring_editor_to_foreground

🐳 Docker 镜像

💻 发展

⚙️ 配置

🔧 故障排除

🤝 贡献

创建发布

📄 许可证

🔗 链接

📚 文档

🌐 资源

📊 项目统计

语言细分

贡献者

🙏 谢谢

⭐ 明星历史

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`unity://project/info`

`unity://console/logs`

`unity://compilation/status`

`unity://editor/playmode`

`unity://scenes/active`

`unity://scenes/active/objects`

`unity://scenes/all`

`unity_trigger_script_compilation`

`unity_create_game_object`

`unity_find_game_object`

`unity_add_component_to_object`

`unity_set_component_field`

`unity_list_scene_objects`

`unity_batch_create_game_objects`

`unity_create_game_object_in_scene`

`unity_create_prefab`

`unity_instantiate_prefab`

`unity_get_prefab_info`

`unity_open_prefab`

`unity_save_prefab`

`unity_close_prefab_stage`

`unity_list_scenes`

`unity_get_active_scene`

`unity_open_scene`

`unity_close_scene`

`unity_save_scene`

`unity_set_active_scene`

`unity_create_script`

`unity_create_asset`

`unity_refresh_assets`

`unity_enter_play_mode`

`unity_exit_play_mode`

`unity_get_play_mode_state`

`unity_run_menu_item`

`unity_bring_editor_to_foreground`