MCP Unity

MCP Unity是一个实现Model Context Protocol的Unity编辑器扩展，通过Node.js服务器桥接AI助手与Unity项目的交互，提供菜单执行、对象选择、组件更新等功能。

开发者工具游戏与游戏化 #Unity扩展 #AI交互 #协议桥接 #编辑器工具本地 .JavaScript

评分 : 5分

下载量 : 13.6K

更新时间 : 2025-04-22

打开站点

什么是MCP Unity?

MCP Unity是将AI助手集成到Unity编辑器的桥梁工具，允许Claude、Windsurf等AI直接操作您的Unity项目。它通过Node.js服务器实现MCP协议，使AI可以执行Unity菜单命令、修改场景对象、运行测试等操作。

如何使用MCP Unity?

只需三步：1) 通过Unity包管理器安装 2) 配置AI客户端 3) 启动服务器即可开始用自然语言控制Unity编辑器。

适用场景

适合需要AI辅助开发、自动化测试、快速原型设计、批量处理场景对象等Unity开发场景。

主要功能

IDE智能集成

自动将Unity包缓存加入VSCode类编辑器，提升AI对项目依赖的理解能力

菜单命令执行

通过自然语言执行任意Unity编辑器菜单命令

场景对象编辑

选择/修改场景中的游戏对象及其组件属性

包管理

通过AI指令安装/管理Unity软件包

测试运行

执行Unity测试运行器中的各种测试

优势

自然语言控制Unity编辑器，提升开发效率

无缝集成主流AI助手(Claude/Windsurf等)

支持完整的Unity编辑功能调用

自动项目环境感知

局限性

需要Node.js运行环境

部分复杂操作仍需手动确认

暂不支持Unity 2022以下版本

如何使用

安装Unity包

通过Unity包管理器安装MCP Unity Window > Package Manager > Add package from git URL

安装Node.js

确保已安装Node.js 18+版本

配置AI客户端

在Unity编辑器中选择Tools > MCP Unity > Server Window进行配置

启动服务器

点击Start Server按钮，等待AI客户端连接

使用案例

创建新对象

通过AI指令在场景中创建新游戏对象

批量修改属性

一次性修改多个游戏对象的相同属性

常见问题

连接失败怎么办？

菜单命令不执行？

🚀 Unity MCP 协议整合指南

本指南将详细介绍如何在 Unity 项目中整合 MCP 协议，涵盖安装、项目结构、运行、配置、调试、故障排查等方面的内容，帮助你快速上手使用。

🚀 快速开始

在开始整合 MCP 协议之前，请确保你已经完成以下步骤：

通过 Git 克隆仓库：

git clone https://github.com/CoderGamester/mcp-unity.git
cd mcp-unity

在 Unity 中导入以下包至 Assets/Package Manager：
- Model Context Protocol
- WebSocketSharp

📦 安装指南

获取代码

使用 Git 克隆仓库：

git clone https://github.com/CoderGamester/mcp-unity.git
cd mcp-unity

在 Unity 中导入指定的包到 Assets/Package Manager：
- Model Context Protocol
- WebSocketSharp

📁 项目结构

mcp-unity/
├── Assets/             # Unity 工程资产
│   ├── Editor/         # MCP 编辑器脚本
│   └── PackageManager/ # 包管理配置文件
├── Server/            # Node.js 服务端代码
│   ├── src/           # 源代码文件夹
│   │   ├── index.ts    # 入口文件
│   │   └── server.ts   # 服务逻辑
│   └── build/         # 编译生成目录
├── .env                # 环境变量配置
└── README.md          # 使用文档

🏃‍♂️ 运行说明

快速启动

在 Unity 中运行编辑器，并确保 MCP 组件已启用。

启动 Node.js 服务：

cd ABSOLUTE/PATH/TO/mcp-unity/Server
npm install && node build/index.js

⚙️ 配置指南

环境变量设置

在根目录创建或编辑 .env 文件，添加以下配置：

LOGGING=true
LOGGING_FILE=false
PORT=8090

服务端参数

通过命令行传递额外参数：

# 设置日志级别
--logLevel debug

# 启用远程调试
--enableRemoteDebugging

🔧 运行时配置

MCP 协议版本

支持以下协议版本：

v1.0.0
v1.1.0（最新版）

网络设置

设置 WebSocket 服务器地址：

ws://localhost:8090

配置 HTTP 接口端点：

"/api/v1"

🐞 调试指南

源码调试

在 Server/src 目录下，添加断点并启动调试程序。

日志输出

启用控制台日志：

set LOGGING=true & set LOGGING_FILE=false

🛠️ 故障排查

连接问题

确认 WebSocket 服务器是否正在运行。
检查防火墙设置，确保端口开放。
验证连接地址和端口配置的正确性。

启动失败

查看 Unity 控制台中的错误信息。
确保 Node.js 已正确安装并加入 PATH。
核对依赖包版本要求。

💬 支持与反馈

问题报告

提交 Issue 到 GitHub
发送邮件至 support@mcprotocol.com

社区交流

参与以下社区讨论：

📚 附录

常见问题解答

如何升级 MCP 版本？ 在 Package Manager 中选择更新选项。
Node.js 服务无法启动怎么办？

检查 npm 包是否安装成功。
确保 Node.js 版本符合要求（>=14.x）。

如何禁用日志输出？ 在 .env 文件中设置 LOGGING=false。

术语表

MCP：Model Context Protocol，模型上下文协议
WebSocket：实时通信协议
npm：Node 包管理工具

📄 许可证

本项目遵循 MIT 开源协议：

MIT License

Copyright (c) 2023 CoderGamester

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.