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:

Clone the repository:
git clone https://github.com/TSavo/Unity-MCP.git cd Unity-MCP
Install dependencies:
npm install
Build the project:
npm run build
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.
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:

execute_code: Execute C# code directly in Unity.
query: Execute a query using dot notation to access objects, properties, and methods.
get_logs: Retrieve logs from AILogger.
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)

Unity-MCP

Integrations

Unity-MCP

Overview

Architecture

Features

Deployment Options

Documentation

Getting Started

Connecting to AI Assistants

Available Tools

Usage Examples

Executing Code in Unity

JSON-RPC Request

JSON-RPC Response

Querying Unity Objects

JSON-RPC Request

JSON-RPC Response

Retrieving Results from AILogger

JSON-RPC Request

JSON-RPC Response

Example Usage

License

Author

Tools

Related Resources