Unity-MCP

A bridge between the Unity game engine and AI assistants using the Model Context Protocol (MCP).

GitHub

Unity-MCP

A bridge between Unity and AI assistants using the Model Context Protocol (MCP).

Overview

Unity-MCP is an open-source implementation of the Model Context Protocol for Unity game development. It enables AI assistants to interact with Unity game environments through a standardized interface, allowing for AI-assisted game development, automated testing, scene analysis, and runtime debugging.

Architecture

The architecture has been simplified to use AILogger for persistence, removing the need for a separate server component:

AI Assistant <-> Unity-MCP STDIO Client <-> Unity Client <-> AILogger
  • AI Assistant: Communicates with the Unity-MCP STDIO Client using the MCP protocol
  • Unity-MCP STDIO Client: Forwards commands to the Unity Client and stores results in AILogger
  • Unity Client: Executes commands in Unity and returns results
  • AILogger: Stores logs and results for later retrieval

The Unity-MCP STDIO Client communicates directly with the Unity Client, which provides endpoints for both code execution and queries. The query tool transforms queries into code execution by wrapping them in a return statement.

Features

  • Execute C# code in the Unity runtime environment
  • Inspect game objects and their components
  • Analyze scene hierarchies and structures
  • Run tests and receive results
  • Invoke methods on game objects and components
  • Modify game state during runtime

Deployment Options

  • Unity Editor Extension: An Editor extension that persists beyond game execution cycles
  • Docker Container: A containerized version that communicates with Unity over the network
  • NPX Package: A Node.js package that can be installed and run via NPX

Documentation

Getting Started

To get started with Unity-MCP, follow these steps:

  1. Clone the repository:

    git clone https://github.com/TSavo/Unity-MCP.git
cd Unity-MCP

  2. Install dependencies:

    npm install

  3. Build the project:

    npm run build

  4. Start the MCP STDIO client:

    npm start

    This will start the MCP STDIO client that communicates with Unity and uses AILogger for persistence.

    Note: Make sure AILogger is running on http://localhost:3030 or set the AI_LOGGER_URL environment variable to point to your AILogger instance.

  5. Run tests:

    # 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"

For more detailed instructions, see the Installation Guide.

Connecting to AI Assistants

To connect the Unity-MCP bridge to an AI assistant, you need to create an MCP configuration file:

{
  "mcpServers": {
    "unity-ai-bridge": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Place this file in the appropriate location for your AI assistant. For Claude, this would typically be in the Claude Desktop app's configuration directory.

Available Tools

The Unity-MCP bridge provides the following tools:

  1. execute_code: Execute C# code directly in Unity.
  2. query: Execute a query using dot notation to access objects, properties, and methods.
  3. get_logs: Retrieve logs from AILogger.
  4. get_log_by_name: Retrieve a specific log from AILogger.

Usage Examples

Executing Code in Unity

You can execute C# code in Unity using the execute_code tool. The code will be executed in the Unity runtime environment, and the result will be stored in AILogger for later retrieval.

JSON-RPC Request

{
  "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 Response

{
  "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}}"
      }
    ]
  }
}

Querying Unity Objects

You can query Unity objects using the query tool. This allows you to access objects, properties, and methods using dot notation.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "query": "Camera.main.transform.position",
      "timeout": 5000
    }
  }
}

JSON-RPC Response

{
  "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}}"
      }
    ]
  }
}

Retrieving Results from AILogger

You can retrieve the results of previous operations from AILogger using the get_log_by_name tool.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_log_by_name",
    "arguments": {
      "log_name": "unity-execute-1712534400000",
      "limit": 1
    }
  }
}

JSON-RPC Response

{
  "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\"}]}"
      }
    ]
  }
}

Example Usage

Once the AI assistant has access to the Unity tool, you can ask it to perform tasks like:

Can you execute the following C# code in Unity?

GameObject.Find("Player").transform.position = new Vector3(0, 1, 0);

License

MIT

Author

T Savo (@TSavo)

相關伺服器