What is Unity Mcp

Unity-MCP is an open-source implementation of the Model Context Protocol (MCP) designed for Unity game development. It facilitates interactions between AI assistants and Unity environments, enabling features such as AI-assisted game development, automated testing, scene analysis, and runtime debugging through a standardized interface.

Use cases

Unity-MCP can be used for various applications, including executing C# code in the Unity runtime, inspecting game objects and their components, analyzing scene hierarchies, running tests, invoking methods on game objects, and modifying game states during runtime. It enhances the development process by enabling real-time interactions between AI and Unity.

How to use

To use Unity-MCP, first clone the repository and install dependencies. Build the project and start the MCP STDIO client. Ensure that AILogger is running, then configure your AI assistant with an MCP configuration file to establish a connection with Unity-MCP. You can execute commands via JSON-RPC requests, such as running C# code or querying Unity objects.

Key features

Unity-MCP offers several key features, including the ability to execute C# code in Unity, inspect game objects, analyze scene hierarchies, run automated tests, invoke methods on game objects, and modify game state during runtime. The integration with AILogger provides a persistent log of actions and results for better debugging and analysis.

Where to use

Unity-MCP can be deployed as a Unity Editor Extension for persistent usage or as a Docker container for network communication. It can also be packaged as an NPX package for easy installation and usage in Node.js environments. These deployment options make it flexible for various development workflows and environments.

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

• MCP Architecture: Overview of the MCP architecture and namespaces
• MCP STDIO Client: Information about the MCP STDIO client and its logging capabilities
• Query Tool: Detailed information about the query tool and how it works
• AILogger Integration: Detailed information about the AILogger integration
• API Reference: Detailed information about the API endpoints
• Installation Guide: Step-by-step instructions for installing and setting up Unity-MCP
• Development Guide: Information about the development environment and workflow
• Hot Reloading Guide: Detailed information about hot reloading in the development environment
• Hot Reloading Quick Reference: Quick reference guide for hot reloading commands and tips
• Contributing Guide: Guidelines for contributing to the project

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)