MCP Unity编辑器（游戏引擎）
     
,/(/. *(/,
*/(((((/. *((((((*.
.*((((((((((/. *((((((((((/.
./((((((((((((((/ *((((((((((((((/,
,/(((((((((((((/*. */(((((((((((((/*.
,%%#((/((((((* ,/(((((/(#&@@(
,%%##%%##((((((/*. ,/((((/(#&@@@@@@(
,%%######%%##((/(((/*. .*/(((//(%@@@@@@@@@@@(
,%%####%#(%%#%%##((/((((((((//#&@@@@@@&@@@@@@@@(
,%%####%( /#%#%%%##(//(#@@@@@@@%, #@@@@@@@(
,%%####%( *#%###%@@@@@@( #@@@@@@@(
,%%####%( #%#%@@@@, #@@@@@@@(
,%%##%%%( #%#%@@@@, #@@@@@@@(
,%%%#* #%#%@@@@, *%@@@(
., ,/##*. #%#%@@@@, ./&@#* *`
,/#%#####%%#/, #%#%@@@@, ,/&@@@@@@@@@&\.
`*#########%%%%###%@@@@@@@@@@@@@@@@@@&*´
`*%%###########%@@@@@@@@@@@@@@&*´
`*%%%######%@@@@@@@@@@&*´
`*#%%##%@@@@@&*´
`*%#%@&*´
███╗ ███╗ ██████╗██████╗ ██╗ ██╗███╗ ██╗██╗████████╗██╗ ██╗
████╗ ████║██╔════╝██╔══██╗ ██║ ██║████╗ ██║██║╚══██╔══╝╚██╗ ██╔╝
██╔████╔██║██║ ██████╔╝ ██║ ██║██╔██╗ ██║██║ ██║ ╚████╔╝
██║╚██╔╝██║██║ ██╔═══╝ ██║ ██║██║╚██╗██║██║ ██║ ╚██╔╝
██║ ╚═╝ ██║╚██████╗██║ ╚██████╔╝██║ ╚████║██║ ██║ ██║
╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝ ╚═╝ MCP Unity是Unity编辑器的模型上下文协议的实现，允许AI助手与您的Unity项目进行交互。此包在Unity和实现MCP协议的Node.js服务器之间提供了一个桥梁，使Cursor、Windsurf、Claude Code、Codex CLI、GitHub Copilot和Google Antigravity等AI代理能够在Unity编辑器中执行操作。
特性
IDE集成-包缓存访问
MCP Unity通过添加Unity提供与VSCode类IDE（Visual Studio Code、Cursor、Windsurf、Google Antigravity）的自动集成 Library/PackedCache 文件夹到您的工作区。此功能：
- 改进Unity软件包的代码智能
- 为Unity软件包提供更好的自动补全和类型信息
- 帮助AI编码助手了解项目的依赖关系
MCP服务器工具
以下工具可用于通过MCP操纵和查询Unity场景和游戏对象：
execute_menu_item：执行Unity菜单项（标记有MenuItem属性的函数）
> 示例提示： “执行菜单项‘游戏对象/创建空游戏对象’以创建新的空游戏对象”
select_gameobject：按路径或实例ID选择Unity层次结构中的游戏对象
> 示例提示： “在我的场景中选择主摄影机对象”
update_gameobject：更新游戏对象的核心属性（名称、标签、层、活动/静态状态），或者在游戏对象不存在时创建游戏对象
> 示例提示： “将玩家对象的标签设置为‘敌人’并使其处于非活动状态”
update_component：更新游戏对象上的组件字段，或者如果游戏对象不包含组件，则将其添加到游戏对象中
> 示例提示： “将刚体组件添加到Player对象并将其质量设置为5”
add_package：在Unity包管理器中安装新包
> 示例提示： “将TextMeshPro包添加到我的项目中”
run_tests：使用Unity测试运行器运行测试
> 示例提示： “运行我项目中的所有EditMode测试”
send_console_log：向Unity发送控制台日志
> 示例提示： “向Unity编辑器发送控制台日志”
add_asset_to_scene：将AssetDatabase中的资源添加到Unity场景中
> 示例提示： “将项目中的播放器预制件添加到当前场景”
create_prefab：使用可选的MonoBehaviour脚本和序列化字段值创建预制件
> 示例提示： “从'PlayerController'脚本创建一个名为'Player'的预制件”
create_scene：创建新场景并将其保存到指定路径
> 示例提示： “在Scenes文件夹中创建一个名为'Level1'的新场景”
load_scene：按路径或名称加载场景，可选择附加加载
> 示例提示： “加载主菜单场景”
delete_scene：按路径或名称删除场景，并将其从“构建设置”中删除
> 示例提示： “从我的项目中删除旧的TestScene”
get_gameobject：获取特定游戏对象的详细信息，包括所有组件
> 示例提示： “获取玩家游戏对象的详细信息”
get_console_logs：从支持分页的Unity控制台检索日志
> 示例提示： “显示Unity控制台的最后20个错误日志”
recompile_scripts：重新编译Unity项目中的所有脚本
> 示例提示： “在我的Unity项目中重新编译脚本”
save_scene：保存当前活动场景，并可选择另存为新路径
> 示例提示： “保存当前场景”或“将场景另存为“资源/场景/Level2.unity””
get_scene_info：获取有关活动场景的信息，包括名称、路径、脏状态和所有加载的场景
> 示例提示： “我的项目中当前加载了哪些场景？”
unload_scene：从层次结构中卸载场景（不删除场景资源）
> 示例提示： “从层次结构中卸载UI场景”
duplicate_gameobject：在场景中复制游戏对象，可选择重命名和重新设置
> 示例提示： “将敌人前言复制5次，并将其重命名为敌人_1到敌人_5”
delete_gameobject：从场景中删除游戏对象
> 示例提示： “从场景中删除旧的Player对象”
reparent_gameobject：更改层次结构中游戏对象的父级
> 示例提示： “将HealthBar对象移动为UI画布的子对象”
move_gameobject：将游戏对象移动到新位置（本地或世界空间）
> 示例提示： 将Player对象移动到世界空间中的位置（10,0,5）
rotate_gameobject：将游戏对象旋转到新的旋转（局部或世界空间、欧拉角或四元数）
> 示例提示： “将相机在Y轴上旋转45度”
scale_gameobject：将游戏对象缩放到新的局部比例
> 示例提示： “将敌方对象缩放到其大小的两倍”
set_transform：在单个操作中设置游戏对象的位置、旋转和比例
> 示例提示： 将立方体的位置设置为（0,5,0），旋转设置为（0,90,0），缩放设置为（2,2,2）
create_material：使用指定的着色器创建新材质并将其保存到项目中
> 示例提示： “使用URP Lit着色器创建名为‘EnemyMaterial’的红色材质”
assign_material：将材质指定给游戏对象的渲染器组件
> 示例提示： “将‘敌方材质’分配给敌方游戏对象”
modify_material：修改现有材质的属性（颜色、浮动、纹理）
> 示例提示： “将‘敌人材质’的颜色更改为蓝色，并将金属色设置为0.8”
get_material_info：获取有关材质的详细信息，包括着色器和所有属性
> 示例提示： “显示“PlayerMaterial”的所有属性”
batch_execute：在单个批处理请求中执行多个工具操作，减少往返次数，并启用原子操作，在失败时可选择回滚
> 示例提示： “在一次批处理操作中创建10个名为Enemy_1到Enemy_10的空游戏对象”
MCP服务器资源
unity://menu-items：检索Unity编辑器中所有可用菜单项的列表，以方便execute_menu_item工具
> 示例提示： “显示与游戏对象创建相关的所有可用菜单项”
unity://scenes-hierarchy：检索当前Unity场景层次结构中所有游戏对象的列表
> 示例提示： “显示当前场景层次结构”
unity://gameobject/{id}：通过场景层次结构中的实例ID或对象路径检索特定游戏对象的详细信息，包括所有具有序列化属性和字段的游戏对象组件
> 示例提示： “获取有关玩家游戏对象的详细信息”
unity://logs：从Unity控制台检索所有日志的列表
> 示例提示： “显示Unity控制台最近的错误消息”
unity://packages：从Unity包管理器中检索有关已安装和可用包的信息
> 示例提示： “列出我的Unity项目中当前安装的所有软件包”
unity://assets：检索Unity资产数据库中的资产信息
> 示例提示： “查找项目中的所有纹理资源”
unity://tests/{testMode}：检索Unity测试运行器中的测试信息
> 示例提示： “列出我的Unity项目中的所有可用测试”
需求
\[！注意\] 带空格的项目路径 MCP Unity支持包含空格的项目路径。但是，如果遇到连接问题，请尝试将项目移动到没有空格的路径，作为故障排除步骤。 示例： - ✅ 推荐：C:\Users\YourUser\Documents\UnityProjects\MyAwesomeGame- ✅ 支持：C:\Users\Your User\Documents\Unity Projects\My Awesome Game
安装
安装此MCP Unity服务器是一个多步骤的过程：
第一步：安装Node.js
要运行MCP Unity服务器，您需要在计算机上安装Node.js 18或更高版本：
Windows
- 访问
- 下载LTS版本的Windows Installer（.msi）（推荐）
- 运行安装程序并按照安装向导进行操作
- 通过打开PowerShell并运行以下命令来验证安装：
node --versionmacOS
- 访问
- 下载LTS版本的macOS安装程序（.pkg）（推荐）
- 运行安装程序并按照安装向导进行操作
- 或者，如果你安装了Homebrew，你可以运行：
brew install node@18- 通过打开终端并运行以下命令来验证安装：
node --version步骤2：通过Unity包管理器安装Unity MCP服务器包
- 打开Unity包管理器（窗口>包管理器）
- 点击左上角的“+”按钮
- 选择“从git URL添加包…”
- 输入：
https://github.com/CoderGamester/mcp-unity.git - 点击“添加”
步骤3：配置AI LLM客户端
Option 1: Configure using Unity Editor
- 打开Unity编辑器
- 导航到“工具”>“MCP Unity”>“服务器窗口”
- 点击AI LLM客户端的“配置”按钮，如下图所示
- 使用给定的弹出窗口确认配置安装
Option 2: Configure Manually
打开AI客户端的MCP配置文件，添加MCP Unity服务器配置：
替换 ABSOLUTE/PATH/TO 使用MCP Unity安装的绝对路径，或者只需从Unity编辑器MCP服务器窗口（工具>MCP Unity>服务器窗口）复制文本。对于基于JSON的客户端 （Cursor、Windsurf、Claude Code、GitHub Copilot等）：
{
"mcpServers": {
"mcp-unity": {
"command": "node",
"args": [
"ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"
]
}
}
}用于Codex CLI (~/.codex/config.toml):
[mcp_servers.mcp-unity]
command = "node"
args = ["ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"]启动Unity编辑器MCP服务器
- 打开Unity编辑器
- 导航到“工具”>“MCP Unity”>“服务器窗口”
- 点击“启动服务器”启动WebSocket服务器
- 打开您的AI编码IDE（例如Cursor、Windsurf、Claude Code、Codex CLI、GitHub Copilot、Google Antigravity等）并开始执行Unity工具
当AI客户端连接到WebSocket服务器时，它将自动显示在窗口中的绿色框中
可选：设置WebSocket端口
默认情况下，WebSocket服务器在端口“8090”上运行。您可以通过两种方式更改此端口：
- 打开Unity编辑器
- 导航到“工具”>“MCP Unity”>“服务器窗口”
- 将“WebSocket端口”值更改为所需的端口号
- Unity将把系统环境变量Unity_PORT设置为新的端口号
- 重启Node.js服务器
- 再次单击“启动服务器”将Unity Editor web套接字重新连接到Node.js MCP服务器
可选：设置超时
默认情况下，MCP服务器和WebSocket之间的超时为10秒。 您可以根据使用的操作系统进行更改：
- 打开Unity编辑器
- 导航到“工具”>“MCP Unity”>“服务器窗口”
- 将“请求超时（秒）”值更改为所需的超时秒数
- Unity将系统环境变量Unity_REST_TIMEOUT设置为新的超时值
- 重启Node.js服务器
- 再次单击“启动服务器”将Unity Editor web套接字重新连接到Node.js MCP服务器
\[！提示\]\ AI编码IDE（例如，Claude Desktop、Cursor IDE、Windsurf IDE）和MCP服务器之间的超时取决于IDE。
可选：允许远程MCP网桥连接
默认情况下，WebSocket服务器绑定到“localhost”。要允许MCP桥接其他机器：
- 打开Unity编辑器
- 导航到“工具”>“MCP Unity”>“服务器窗口”
- 启用“允许远程连接”复选框
- Unity将WebSocket服务器绑定到“0.0.0.0”（所有接口）
- 重新启动Node.js服务器以应用新的主机配置
- 远程运行MCP网桥时，将环境变量UNITY_HOST设置为UNITY计算机的IP地址：
UNITY_HOST=192.168.1.100 node server.js
调试服务器
Building the Node.js Server
MCP Unity服务器是使用Node.js构建的。它需要将TypeScript代码编译为JavaScript build 目录。 如果出现问题，您可以通过以下方式强制安装：
- 打开Unity编辑器
- 导航到“工具”>“MCP Unity”>“服务器窗口”
- 点击“强制安装服务器”按钮
如果你想手动构建它，你可以按照以下步骤操作：
- 打开终端/PowerShell/命令提示符
- 导航到服务器目录：
cd ABSOLUTE/PATH/TO/mcp-unity/Server~- 安装依赖项：
npm install- 构建服务器：
npm run build- 运行服务器：
node build/index.jsDebugging with MCP Inspector
使用调试服务器 @模型上下文协议/检查器:
- PowerShell
npx @modelcontextprotocol/inspector node Server~/build/index.js- 命令提示符/终端
npx @modelcontextprotocol/inspector node Server~/build/index.js别忘了用以下命令关闭服务器 Ctrl + C 在关闭终端或使用 MCP检查员.
Enable Console Logs
- 允许在终端上登录或登录log.txt文件：
- PowerShell
$env:LOGGING = "true"
$env:LOGGING_FILE = "true"- 命令提示符/终端
set LOGGING=true
set LOGGING_FILE=true常见问题
What is MCP Unity?
MCP Unity是一个强大的桥梁，它使用模型上下文协议（MCP）将Unity编辑器环境连接到AI助手LLM工具。
本质上，MCP Unity：
- 将Unity编辑器功能（如创建对象、修改组件、运行测试等）作为AI可以理解和使用的“工具”和“资源”公开。
- 在Unity中运行一个WebSocket服务器和一个实现MCP的Node.js服务器（充当Unity的WebSocket客户端）。这允许AI助手向Unity发送命令并接收信息。
- 使您能够与AI助手一起使用自然语言提示来执行Unity项目中的复杂任务，从而显著加快开发工作流程。
Why use MCP Unity?
MCP Unity为开发人员、艺术家和项目经理提供了几个引人注目的优势：
- 加速发展： 自动化重复性任务，生成样板代码，并使用AI提示管理资产。这可以腾出你的时间来专注于创造性和复杂的问题解决。
- 提高生产率： 与Unity编辑器功能交互，无需手动点击菜单或编写脚本进行简单操作。你的AI助手成为你在Unity中能力的直接延伸。
- 改进的可访问性： 允许不太熟悉Unity编辑器或C#脚本的深度复杂性的用户仍然可以通过AI指导对项目做出有意义的贡献和修改。
- 无缝集成： 设计用于与支持MCP的各种AI助手和IDE配合使用，提供了一种在整个开发工具包中利用AI的一致方式。
- 可扩展性： 协议和工具集可以扩展。您可以定义新的工具和资源，将更多特定于项目或Unity的功能暴露给AI。
- 合作潜力： 促进了一种新的协作方式，人工智能可以帮助完成传统上由团队成员完成的任务，或者通过指导新开发人员完成项目结构和操作来帮助他们入职。
How does MCP Unity compare with the upcoming Unity 6.2 AI features?
Unity 6.2将引入新的内置AI工具，包括之前的Unity Muse（用于纹理和动画生成等生成AI功能）和Unity Sentis（用于在Unity运行时运行神经网络）。由于Unity 6.2尚未完全发布，此比较基于公开信息和预期功能：
- 集中：
- MCP Unity： 主要侧重于 编辑自动化和交互它允许外部AI（如基于LLM的编码助手） *控制和查询Unity编辑器本身* 操纵场景、资源和项目设置。这是关于增强 *开发人员的工作流程* 在编辑器内。 - Unity 6.2 AI： - 旨在在编辑器内创建内容（生成纹理、精灵、动画、行为、脚本），并为常见任务提供人工智能辅助，直接集成到Unity编辑器界面中。 - 一个经过微调的模型，可以询问有关Unity文档和API结构的任何问题，定制的示例更准确地反映Unity的环境。 - 添加运行AI模型推理的功能，允许开发人员部署和运行预训练的神经网络 *在您的游戏或应用程序中* 用于NPC行为、图像识别等功能。
- 使用案例：
- MCP Unity： “创建一个新的3D对象，将其命名为‘Player’，添加一个刚体，并将其质量设置为10。”“运行所有播放模式测试。”“要求修复控制台日志上的错误。”“执行自定义菜单项‘为iOS准备构建’并修复可能出现的任何错误。” - Unity 6.2 AI： “为此材质生成科幻纹理。”“更新场景中所有树木的位置，将其放置在标记为“森林”的地形区域内。”“为此角色创建行走动画。”“生成2D精灵以完成角色。”“在控制台日志上询问有关错误的详细信息。”
- 互补而非相互排斥：
MCP Unity和Unity的原生AI工具可以看作是互补的。您可以使用MCP Unity和您的AI编码助手来设置场景或批量修改资源，然后使用Unity AI工具生成特定纹理，或为其中一个资源创建动画或2D精灵。MCP Unity提供了一种灵活的、基于协议的方式与编辑器进行交互，对于想要与更广泛的外部AI服务集成或构建自定义自动化工作流程的开发人员来说，这种方式非常强大。
What MCP hosts and IDEs currently support MCP Unity?
MCP Unity旨在与任何可以充当MCP客户端的AI助手或开发环境配合使用。生态系统正在增长，但目前已知的集成或兼容平台包括：
- 光标
- 帆板运动
- 克劳德桌面版
- 克劳德代码
- Codex CLI
- GitHub Copilot
- 谷歌反重力
Can I extend MCP Unity with custom tools for my project?
是的，当然！MCP Unity架构的一个显著优点是它的可扩展性。
- 在Unity（C#）中： 您可以创建新的C#类，这些类继承自
McpToolBase（或类似的资源库）以公开自定义Unity编辑器功能。然后，这些工具将在中注册McpUnityServer.cs例如，您可以编写一个工具来自动化项目特有的特定资产导入管道。 - 在Node.js服务器（TypeScript）中： 然后，您将在
Server/src/tools/目录，包括其用于输入/输出的Zod模式，并将其注册到Server/src/index.ts。此Node.js部分将把请求转发到Unity中的新C#工具。
这允许您根据游戏或应用程序的特定需求和工作流程定制AI的功能。
Is MCP Unity free to use?
是的，MCP Unity是一个根据MIT许可证分发的开源项目。您可以根据许可条款自由使用、修改和分发它。
Why am I unable to connect to MCP Unity?
- 确保WebSocket服务器正在运行（检查Unity中的服务器窗口）
- 从MCP客户端发送控制台日志消息，以强制MCP客户端和Unity服务器之间重新连接
- 在Unity编辑器MCP服务器窗口中更改端口号。（工具>MCP Unity>服务器窗口）
Why won't the MCP Unity server start?
- 检查Unity控制台是否有错误消息
- 确保Node.js已正确安装并可在PATH中访问
- 验证所有依赖项是否已安装在Server目录中
Why do I get a connection failed error when running Play Mode tests?
这 run_tests 工具返回以下响应：
Error:
Connection failed: Unknown error发生此错误的原因是，当切换到播放模式时域重新加载时，网桥连接丢失。解决方法是关闭 重新加载域 在 编辑>项目设置>编辑器>“进入播放模式设置”.
Why do some clients fail with KeyError: 'position' during tool initialization?
当某些MCP客户端包含本地JSON指针引用时，它们在解析工具架构时可能会失败，例如 #/properties/position.
MCP Unity通过注册转换工具输入来避免这种情况(set_transform, move_gameobject, rotate_gameobject, scale_gameobject)每个字段都有新的嵌套向量模式，因此生成的模式不依赖于本地模式 #/properties/... 参考文献
如果您仍然看到此错误：
- 将您的MCP客户端更新到最新版本，
- 重建节点服务器(
cd Server~ && npm run build), - 确认您的软件包版本包含此兼容性修复程序。
故障排除：WSL2（Windows 11）网络
当Unity在Windows 11上运行时，在WSL2中运行MCP（Node.js）服务器，连接到 ws://localhost:8090/McpUnity 可能会失败 ECONNREFUSED.
原因：WSL2和Windows具有单独的网络命名空间-- localhost WSL2内部不指向Windows主机。默认情况下，Unity会监听 localhost:8090.
解决方案1--启用WSL2镜像模式网络（首选）
- Windows 11：设置→ 系统→ 对于开发者→ WSL → 启用“镜像模式网络”。
- 或通过
.wslconfig（然后运行wsl --shutdown并重新打开WSL）：
[wsl2]
networkingMode=mirrored在启用之后， localhost 在Windows和WSL2之间共享，因此默认配置(localhost:8090)工作。
解决方案2——将节点客户端指向Windows主机
在启动MCP客户端之前，在WSL shell中设置：
# Use the Windows host IP detected from resolv.conf
export UNITY_HOST=$(grep -m1 nameserver /etc/resolv.conf | awk '{print $2}')有了这个， Server~/src/unity/mcpUnity.ts 将连接到 ws://$UNITY_HOST:8090/McpUnity 而不是 localhost （上面写着 UNITY_HOST，也可能尊重 Host 在 ProjectSettings/McpUnitySettings.json 如果存在）。
解决方案3——允许从Unity进行远程连接
- Unity：工具→ MCP Unity→ 服务器窗口→ 启用“允许远程连接”（Unity绑定到
0.0.0.0). - 确保Windows防火墙允许在配置的端口（默认8090）上使用入站TCP。
- 从WSL2连接到Windows主机IP（请参阅解决方案2）或
localhost如果启用了镜像模式。
\[！注意\] 默认端口为8090。您可以在Unity服务器窗口（工具）中更改它→ MCP Unity→ 服务器窗口）。该值映射到McpUnitySettings并坚持ProjectSettings/McpUnitySettings.json.
验证连接
npm i -g wscat
# After enabling mirrored networking
wscat -c ws://localhost:8090/McpUnity
# Or using the Windows host IP
wscat -c ws://$UNITY_HOST:8090/McpUnity运行测试
C#测试（Unity）
使用Unity的测试运行器运行测试：
- 打开Unity编辑器
- 导航到“窗口”>“常规”>“测试运行器”
- 选择“编辑模式”选项卡
- 点击“全部运行”以执行所有测试
TypeScript测试（服务器）
使用Jest运行测试：
cd Server~
npm test要在监视模式下运行测试，请执行以下操作：
npm run test:watch支持与反馈
如果您有任何问题或需要支持，请打开 问题 在这个存储库或替代方案中，您可以联系：
- Linkedin： 
- 不和码：gamester7178
- 电子邮件：game.gamester@gmail.com
贡献
欢迎投稿！请随时提交拉取请求或用您的请求打开问题。
提交您的更改 遵循 约定式提交 格式。
许可证
该项目正在进行中 MIT许可证