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 包

文档

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 实例。
运行测试：
# 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 ）

Unity-MCP

Integrations

Unity-MCP

概述

建筑学

特征

部署选项

文档

入门

连接AI助手

可用工具

使用示例

在 Unity 中执行代码

JSON-RPC 请求

JSON-RPC 响应

查询 Unity 对象

JSON-RPC 请求

JSON-RPC 响应

从 AILogger 检索结果

JSON-RPC 请求

JSON-RPC 响应

示例用法

执照

作者

Tools

Related Resources