UnityMCP

UnityMCP 是一款功能强大的 Unity 编辑器插件，实现了模型上下文协议（MCP），能够实现 Unity 与 AI 助手之间的无缝集成。它提供实时编辑器状态监控、远程命令执行以及全面的日志记录功能。

架构

该项目由两个主要组件组成：

1. Unity 插件（UnityMCPPlugin）

一个 Unity 编辑器插件，提供以下功能：

• 用于连接状态和监控的调试窗口
• 用于实时通信的 WebSocket 客户端
• C# 代码执行引擎
• 全面的日志系统
• 编辑器状态跟踪和序列化

2. MCP 服务器（unity-mcp-server）

一个基于 TypeScript 的 MCP 服务器，通过标准化工具公开 Unity 编辑器的功能：

可用工具

1. get_editor_state

   • 获取当前 Unity 编辑器状态
   • 包括活动的游戏对象、选中状态、播放模式状态
   • 提供场景层级和项目结构
   • 支持不同输出格式（原始、仅脚本、无脚本）

2. execute_editor_command

   • 直接在 Unity 编辑器中执行 C# 代码
   • 完全访问 UnityEngine 和 UnityEditor API
   • 实时执行并具有全面的错误处理
   • 命令超时保护

3. get_logs

   • 检索并过滤 Unity 编辑器日志
   • 支持按类型、内容和时间戳进行过滤
   • 可自定义输出字段
   • 缓冲区管理以优化性能

安装

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 UnityMCP：

npx -y @smithery/cli install @Arodoid/unitymcp --client claude

先决条件

• Unity 2022.3 或更高版本
• Node.js 18 或更高版本
• npm 9 或更高版本

Unity 插件设置

1. 将 UnityMCPPlugin 文件夹复制到您的 Unity 项目 Assets 目录中
2. 打开 Unity 编辑器
3. 通过 Unity 的顶部菜单栏 > UnityMCP > 调试窗口访问插件

MCP 服务器设置

cd unity-mcp-server
npm install
npm run build

使用

启动服务器

cd unity-mcp-server
node build/index.js

从 Unity 连接

1. 打开您的 Unity 项目
2. 打开 UnityMCP 调试窗口（Window > UnityMCP > 调试窗口）
3. 插件将自动尝试连接到 MCP 服务器
4. 在调试窗口中监控连接状态和日志

示例：执行命令

// 将选中的对象居中
Selection.activeGameObject.transform.position = Vector3.zero;

// 切换播放模式
EditorApplication.isPlaying = !EditorApplication.isPlaying;

// 创建一个新的立方体
GameObject.CreatePrimitive(PrimitiveType.Cube);

开发

构建服务器

cd unity-mcp-server
npm run build

监视更改

npm run watch

检查 MCP 通信

npm run inspector

技术细节

通信协议

• 基于 WebSocket 的通信，使用 8080 端口
• 双向实时更新
• 所有通信均采用 JSON 消息格式
• 自动重连处理

安全特性

• 命令执行超时保护
• 错误处理和验证
• 日志缓冲区管理
• 连接状态监控

错误处理

系统提供全面的错误处理机制，用于处理：

• 连接问题
• 命令执行失败
• 编译错误
• 运行时异常
• 超时情况

贡献

1. 分支仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m '添加惊人功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

本项目采用知识共享署名-非商业性使用 4.0 国际许可协议（CC BY-NC 4.0）授权。

UnityMCP 快速上手指南

UnityMCP 是一款强大的 Unity Editor 插件，基于模型上下文协议（MCP）构建，能够实现 Unity 编辑器与 AI 助手的无缝集成。它支持实时编辑器状态监控、远程 C# 命令执行以及全面的日志管理功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Unity: 2022.3 或更高版本
• Node.js: 18 或更高版本
• npm: 9 或更高版本
• 操作系统: Windows, macOS 或 Linux

提示：国内开发者若遇到 npm 安装缓慢的问题，可临时切换至淘宝镜像源： npm config set registry https://registry.npmmirror.com

安装步骤

1. 安装 MCP Server (服务端)

克隆项目或直接下载源码后，在终端进入 unity-mcp-server 目录进行构建：

cd unity-mcp-server
npm install
npm run build

(可选) 如果您使用 Claude Desktop 且希望通过 Smithery 自动安装配置：

npx -y @smithery/cli install @Arodoid/unitymcp --client claude

2. 安装 Unity Plugin (客户端)

1. 将项目中的 UnityMCPPlugin 文件夹复制到您的 Unity 项目的 Assets 目录下。
2. 打开或重启 Unity Editor。
3. 在顶部菜单栏选择 UnityMCP > Debug Window 即可看到插件界面。

基本使用

第一步：启动服务

在终端中运行构建好的服务端程序（默认监听 8080 端口）：

cd unity-mcp-server
node build/index.js

第二步：连接 Unity

1. 在 Unity 编辑器中打开 Window > UnityMCP > Debug Window。
2. 插件会自动尝试连接本地运行的 MCP 服务器。
3. 观察调试窗口中的状态指示器，确认连接成功（通常显示为绿色或 "Connected"）。

第三步：执行命令示例

连接成功后，您可以通过 AI 助手或直接调用工具向 Unity 发送 C# 指令。以下是几个典型的操作示例：

示例 1：重置选中物体位置

// 将当前选中的 GameObject 移动到世界原点
Selection.activeGameObject.transform.position = Vector3.zero;

示例 2：切换播放模式

// 切换 Play 模式的开启/关闭状态
EditorApplication.isPlaying = !EditorApplication.isPlaying;

示例 3：创建基础几何体

// 在当前场景创建一个立方体
GameObject.CreatePrimitive(PrimitiveType.Cube);

执行上述命令后，您将立即在 Unity 场景中看到对应的变化，同时可以在 Debug Window 中查看执行日志和结果。