Unity MCP

🚀 Unity-MCP Project Guide

Unity-MCP (Unity-Multiplayer Collaboration Protocol) is an open-source toolkit for integrating AI agents with the Unity game engine. It enables AI agents to interact with Unity games via the JSON-RPC protocol and perform complex game logic tasks.

🚀 Quick Start

This guide will help you quickly integrate AI agents with your Unity game and implement various interesting features!

✨ Features

• Allows AI agents to interact with Unity games through the JSON-RPC protocol.
• Enables the execution of complex game logic tasks.

📦 Installation

Clone the Repository

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

Install .NET SDK

Ensure you have installed .NET SDK version 5.0 or higher. If not, you can download and install it from the official link.

Build the Project

dotnet build src/UnityMCP.sln

Configure API Key

Add the following content to appsettings.json:

{
  "ApiKey": "your_project_key_here",
  "LogLevel": "Information"
}

📚 Documentation

Logging and Querying

Data Structure

Log entries contain the following fields:

• id: Unique identifier (GUID)
• name: Log name (generated by the tool)
• data: Stored result data or error information
• timestamp: Recording time (ISO 8601 format)

Query Syntax

Use the Unity Query Language (UQL) for operations:

// Get the list of active players
GET /api/players?active=true

// Create a new scene
POST /api/scenes
{
  "name": "New Scene",
  "settings": { ... }
}

💻 Usage Examples

Execute Code

Request example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
      "code": "Debug.Log(\"你好，Unity!\"); return GameObject.FindObjectsOfType<GameObject>().Length;",
      "超时时间": 5000
    }
  }
}

Response example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "内容": [
      {
        "类型": "文本",
        "文本": "{\"状态\":\"成功\",\"日志名称\":\"unity-execute-1712534400000\",\"结果\":{\"成功\":true,\"结果\":42,\"日志\":[\"你好，Unity!\"]}"
      }
    ]
  }
}

Query Objects

Request example:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "查询": "Camera.main.transform.position",
      "超时时间": 5000
    }
  }
}

Response example:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "内容": [
      {
        "类型": "文本",
        "文本": "{\"x\":10.5,\"y\":-3.2,\"z\":5.8}"
      }
    ]
  }
}

Retrieve Results

Use the following command to view logs:

dotnet run -- --query "SELECT * FROM logs"

📄 License

This project is licensed under the MIT License. For details, please refer to the LICENSE file.

👨‍💻 Author Information

• Author: 张三
• Email: contact@zhangsan.com
• GitHub Link: Unity-MCP