Unity-MCP
使用模型上下文协议 (MCP) 在 Unity 和 AI 助手之间建立桥梁。
概述
Unity-MCP 是 Unity 游戏开发的模型上下文协议 (MCP) 的开源实现。它使 AI 助手能够通过标准化接口与 Unity 游戏环境进行交互，从而实现 AI 辅助游戏开发、自动化测试、场景分析和运行时调试。
建筑学
该架构已简化为使用 AILogger 进行持久化，从而无需单独的服务器组件：
AI Assistant <-> Unity-MCP STDIO Client <-> Unity Client <-> AILogger
- AI 助手：使用 MCP 协议与 Unity-MCP STDIO 客户端进行通信
- Unity-MCP STDIO 客户端：将命令转发到 Unity 客户端并将结果存储在 AILogger 中
- Unity Client ：在Unity中执行命令并返回结果
- AILogger ：存储日志和结果以供日后检索
Unity-MCP STDIO 客户端直接与 Unity 客户端通信，后者提供代码执行和查询的端点。查询工具通过将查询包装在return语句中，将其转换为代码执行。
特征
- 在 Unity 运行时环境中执行 C# 代码
- 检查游戏对象及其组件
- 分析场景层次和结构
- 运行测试并接收结果
- 调用游戏对象和组件的方法
- 在运行时修改游戏状态
部署选项
- Unity 编辑器扩展：一个在游戏执行周期之外持续存在的编辑器扩展
- Docker 容器：通过网络与 Unity 通信的容器化版本
- NPX 包：可以通过 NPX 安装和运行的 Node.js 包
文档
入门
要开始使用 Unity-MCP，请按照以下步骤操作：
- 克隆存储库：
git clone https://github.com/TSavo/Unity-MCP.git
cd Unity-MCP
- 安装依赖项：
- 构建项目：
- 启动 MCP STDIO 客户端：这将启动与 Unity 通信并使用 AILogger 进行持久化的 MCP STDIO 客户端。注意：确保 AILogger 在http://localhost:3030上运行或设置 AI_LOGGER_URL 环境变量以指向您的 AILogger 实例。
- 运行测试：
# Run all tests
npm test
# Run only unit tests
npm run test:unit
# Run only e2e tests
npm run test:e2e
# Run tests with a specific pattern
npm test -- --testNamePattern="should return the server manifest"
npm run test:unit -- --testNamePattern="should return the server manifest"
npm run test:e2e -- --testNamePattern="should discover the test server"
有关更详细的说明，请参阅安装指南。
连接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(\"Hello from 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\":[\"Hello from 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\":[\"Hello from Unity!\"],\"executionTime\":123},\"timestamp\":\"2025-04-08T00:00:00.000Z\"},\"timestamp\":\"2025-04-08T00:00:00.000Z\"}]}"
}
]
}
}
示例用法
一旦 AI 助手可以访问 Unity 工具，您就可以要求它执行以下任务：
Can you execute the following C# code in Unity?
GameObject.Find("Player").transform.position = new Vector3(0, 1, 0);
执照
麻省理工学院
作者
T Savo（ @TSavo ）