项目介绍
Unity-MCP
Unity与AI助手之间使用模型上下文协议（MCP）的桥梁。
概述
Unity-MCP是Unity游戏开发中Model Context Protocol的一个开源实现。它使AI助手能够通过标准化接口与Unity游戏环境进行交互，支持AI辅助的游戏开发、自动化测试、场景分析和运行时调试。
架构
架构已简化为使用AILogger进行持久化，无需单独的服务器组件：
AI助手 <-> Unity-MCP STDIO客户端 <-> Unity客户端 <-> AILogger
- AI助手：使用MCP协议与Unity-MCP STDIO客户端通信
- Unity-MCP STDIO客户端：转发命令给Unity客户端，并将结果存储在AILogger中
- Unity客户端：执行Unity中的命令并返回结果
- AILogger：存储日志和结果以供后续检索
Unity-MCP STDIO客户端直接与Unity客户端通信，提供代码执行和查询的端点。查询工具通过将其包装在一个return语句中，将查询转换为代码执行。
特性
- 在Unity运行时环境中执行C#代码
- 检查游戏对象及其组件
- 分析场景层次结构和结构
- 运行测试并接收结果
- 调用游戏对象和组件的方法
- 在运行时修改游戏状态
部署选项
- Unity编辑器扩展：一个超出游戏执行周期的编辑器扩展
- Docker容器：一个通过网络与Unity通信的容器化版本
- NPX包：一个可以通过NPX安装和运行的Node.js包
文档
- MCP架构：关于MCP架构和命名空间的概述
- MCP STDIO客户端：关于MCP STDIO客户端及其日志功能的信息
- 查询工具：关于查询工具及其工作原理的详细信息
- AILogger集成：关于AILogger集成的详细信息
- API参考：关于API端点的详细信息
- 安装指南：逐步安装和设置Unity-MCP的说明
- 开发指南：关于开发环境和工作流程的信息
- 热重载指南：关于开发环境中热重载的详细信息
- 热重载快速参考：关于热重载命令和技巧的快速参考指南
- 贡献指南：项目贡献的指导方针
开始使用
要开始使用Unity-MCP，请按照以下步骤操作：
-
克隆仓库：
git clone https://github.com/TSavo/Unity-MCP.git cd Unity-MCP -
安装依赖项：
npm install -
构建项目：
npm run build -
启动MCP STDIO客户端：
npm start这将启动与Unity通信并使用AILogger进行持久化的MCP STDIO客户端。
注意：确保AILogger正在http://localhost:3030上运行，或者设置AI_LOGGER_URL环境变量指向你的AILogger实例。
-
运行测试：
# 运行所有测试 npm test # 只运行单元测试 npm run test:unit # 只运行端到端测试 npm run test:e2e # 使用特定模式运行测试 npm test -- --testNamePattern="应返回服务器清单" npm run test:unit -- --testNamePattern="应返回服务器清单" npm run test:e2e -- --testNamePattern="应发现测试服务器"
更多详细说明，请参阅安装指南。
连接到AI助手
要将Unity-MCP桥连接到AI助手，您需要创建一个MCP配置文件：
{
"mcpServers": {
"unity-ai-bridge": {
"url": "http://localhost:8080/sse"
}
}
}
将此文件放置在您的AI助手的适当位置。对于Claude，这通常是在Claude桌面应用的配置目录中。
可用工具
Unity-MCP桥提供了以下工具：
- execute_code：直接在Unity中执行C#代码。
- query：使用点表示法访问对象、属性和方法来执行查询。
- get_logs：从AILogger检索日志。
- get_log_by_name：从AILogger检索特定的日志。
使用示例
在Unity中执行代码
您可以使用execute_code工具在Unity中执行C#代码。该代码将在Unity运行时环境中执行，结果将存储在AILogger中以供后续检索。
JSON-RPC请求
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "execute_code",
"arguments": {
"code": "Debug.Log(\"来自Unity的问候！\"); return GameObject.FindObjectsOfType<GameObject>().Length;",
"timeout": 5000
}
}
}
JSON-RPC响应
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"status\":\"success\",\"logName\":\"unity-execute-1712534400000\",\"result\":{\"success\":true,\"result\":42,\"logs\":[\"来自Unity的问候！\"],\"executionTime\":123}}"
}
]
}
}
查询Unity对象
您可以使用query工具查询Unity对象。这允许您使用点表示法访问对象、属性和方法。
JSON-RPC请求
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "query",
"arguments": {
"query": "Camera.main.transform.position",
"timeout": 5000
}
}
}
JSON-RPC响应
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [
{
"type": "text",
"text": "{\"status\":\"success\",\"logName\":\"unity-query-1712534400000\",\"result\":{\"success\":true,\"result\":{\"x\":0,\"y\":1,\"z\":-10},\"executionTime\":45}}"
}
]
}
}
从AILogger检索结果
您可以使用get_log_by_name工具从AILogger检索先前操作的结果。
JSON-RPC请求
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "get_log_by_name",
"arguments": {
"log_name": "unity-execute-1712534400000",
"limit": 1
}
}
}
JSON-RPC响应
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "{\"status\":\"success\",\"name\":\"unity-execute-1712534400000\",\"entries\":[{\"id\":\"123e4567-e89b-12d3-a456-426614174000\",\"name\":\"unity-execute-1712534400000\",\"data\":{\"result\":{\"success\":true,\"result\":42,\"logs\":[\"来自Unity的问候！\"],\"executionTime\":123},\"timestamp\":\"2025-04-08T00:00:00.000Z\"},\"timestamp\":\"2025-04-08T00:00:00.000Z\"}]}"
}
]
}
}
示例用法
一旦AI助手可以访问Unity工具，您可以要求它执行任务，如：
你能在Unity中执行以下C#代码吗？
GameObject.Find("玩家").transform.position = new Vector3(0, 1, 0);
许可证
MIT
作者
T Savo (@TSavo)