Unity-MCP
使用模型上下文协议 (MCP) 在 Unity 和 AI 助手之间建立桥梁。
概述
Unity-MCP 是 Unity 游戏开发的模型上下文协议 (MCP) 的开源实现。它使 AI 助手能够通过标准化接口与 Unity 游戏环境进行交互，从而实现 AI 辅助游戏开发、自动化测试、场景分析和运行时调试。
建筑学
该架构已简化为使用 AILogger 进行持久化，从而无需单独的服务器组件：
AI Assistant <-> Unity-MCP STDIO Client <-> Unity Client <-> AILoggerAI 助手：使用 MCP 协议与 Unity-MCP STDIO 客户端进行通信
Unity-MCP STDIO 客户端：将命令转发到 Unity 客户端并将结果存储在 AILogger 中
Unity Client ：在Unity中执行命令并返回结果
AILogger ：存储日志和结果以供日后检索
Unity-MCP STDIO 客户端直接与 Unity 客户端通信，后者提供代码执行和查询的端点。查询工具通过将查询包装在return语句中，将其转换为代码执行。
Related MCP server: Advanced Unity MCP
特征
在 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 ）