What Is Unity MCP? An Extensible Unity Editor Framework for AI Tool Integration

Unity MCP is an open-source Unity Editor extension that implements the Model Context Protocol (MCP), enabling AI language models to communicate with Unity projects via TCP/IP to execute commands, query resources, and run custom prompts.

Unity MCP (Model Context Protocol) bridges AI assistants like Claude and GPT-4 with the Unity Editor through a bidirectional TCP channel. Developed by isuzu-shiranui as a pluggable C# framework, it exposes Unity's internal APIs as structured tools that AI agents can invoke programmatically. The architecture separates concerns between a TypeScript MCP client and a Unity C# server, allowing developers to extend functionality by implementing simple handler interfaces that auto-register at editor startup.

Core Architecture of Unity MCP

The framework implements the official Model Context Protocol specification across two distinct layers: a TypeScript client that initiates requests and a Unity C# server that processes them. This separation allows AI services to remain unaware of Unity's internals while still manipulating scenes, assets, and editor state programmatically.

The Model Context Protocol Implementation

At its heart, Unity MCP translates between MCP messages and Unity Editor API calls. The TypeScript side acts as an McpServer-like client that sends commands, resource requests, and prompt definitions over TCP. On the Unity side, the McpServer class in Editor/Core/McpServer.cs listens for these connections, deserializes incoming JSON using Newtonsoft.Json, and dispatches requests to registered handlers. Every response returns a structured JSON envelope containing status, result, or error fields, ensuring AI agents receive predictable, parseable feedback.

TCP Communication and Discovery

The server establishes a persistent TCP connection—defaulting to port 27182—between the TypeScript client and Unity Editor. For seamless integration, Unity MCP includes optional UDP broadcast discovery via the StartUdpListener method in McpServer.cs, allowing the TypeScript client to locate the Unity editor automatically without manual IP configuration. All network operations are thread-safe; the server queues Unity API calls to the main editor thread using ExecuteOnMainThread, preventing crashes when handlers interact with scene objects or the AssetDatabase from background threads.

How Unity MCP Handles Requests

Unity MCP processes incoming requests through a pluggable handler system. Developers extend the framework by implementing standardized interfaces that the server discovers and registers automatically at editor startup.

Command Handlers (IMcpCommandHandler)

Command handlers perform actions within the Unity Editor. By implementing the IMcpCommandHandler interface defined in Editor/Core/IMcpCommandHandler.cs, developers create classes that expose specific actions to AI agents. Each handler specifies a CommandPrefix (e.g., "scene", "asset") and implements an Execute method that receives an action string and JSON parameters. The server routes commands using the format prefix.action, enabling granular control over editor operations like creating GameObjects or executing runtime code.

Resource Handlers (IMcpResourceHandler)

Resource handlers provide read-only data about the Unity project state. Defined in Editor/Core/IMcpResourceHandler.cs, these handlers answer queries such as listing installed packages or enumerating loaded assemblies. The framework includes built-in examples like AssembliesResourceHandler.cs and PackagesResourceHandler.cs, which demonstrate how to expose Unity's internal state as MCP resources that AI models can query to understand project context before suggesting modifications.

Auto-Discovery and Registration

The McpHandlerDiscovery.cs file contains the reflection-based discovery system that scans Editor folders for handler implementations at startup. Rather than requiring manual registration, the system automatically instantiates and registers valid handlers with the server. Each handler's enabled state persists in Unity preferences via McpSettings.cs, allowing developers to toggle specific AI capabilities from the Unity MCP preferences panel without removing code.

Implementing a Custom Command Handler

Creating new AI-accessible functionality requires only a single C# class placed in an Editor folder. The discovery system handles the rest.

C# Handler Implementation

The following example implements a custom greeting command that AI agents can invoke:

using Newtonsoft.Json.Linq;
using UnityMCP.Editor.Core;

namespace MyUnityMCP.Handlers
{
    internal sealed class HelloWorldHandler : IMcpCommandHandler
    {
        public string CommandPrefix => "hello";
        public string Description   => "Returns a greeting from the Unity editor.";

        public JObject Execute(string action, JObject parameters)
        {
            if (action != "greet")
                return new JObject { ["status"] = "error", ["message"] = $"Unsupported action {action}" };

            var name = parameters["name"]?.ToString() ?? "World";
            return new JObject
            {
                ["status"] = "success",
                ["result"] = new JObject { ["greeting"] = $"Hello, {name}!" }
            };
        }
    }
}

Place this file anywhere in an Editor folder. The discovery system in McpHandlerDiscovery.cs will automatically register it on the next editor startup.

TypeScript Client Invocation

AI agents or external tools interact with the handler through standard TCP sockets. The TypeScript client sends JSON-RPC-like messages and awaits structured responses:

import net from "net";

const client = net.createConnection({ host: "127.0.0.1", port: 27182 }, () => {
  const request = {
    type: "command",
    command: "hello.greet",
    params: { name: "Alice" },
    id: "req-1"
  };
  client.write(JSON.stringify(request) + "\n");
});

client.on("data", (data) => {
  console.log("Response:", data.toString());
});

The Unity server processes this through ProcessData in McpServer.cs, routes it to the HelloWorldHandler, and returns:

{
  "status": "success",
  "result": {"greeting": "Hello, Alice!"},
  "id": "req-1"
}

Configuration and Settings

Unity MCP stores configuration in McpSettings.asset, managed by Editor/Settings/McpSettings.cs. This persistence layer tracks which handlers are enabled, allowing developers to disable specific AI capabilities without removing handler code. The settings panel integrates directly into Unity's Preferences window, providing a GUI for toggling handler states and configuring network parameters like the TCP port and UDP discovery settings.

Summary

• Unity MCP is an open-source framework that connects AI models to Unity via the Model Context Protocol over TCP/IP.
• Handler architecture separates commands (IMcpCommandHandler) from resources (IMcpResourceHandler), enabling both action execution and project introspection.
• Auto-discovery in McpHandlerDiscovery.cs eliminates manual registration; place handler files in Editor folders and they register automatically.
• Thread safety is enforced through ExecuteOnMainThread in McpServer.cs, ensuring all Unity API calls occur on the main editor thread.
• Built-in handlers like AssembliesResourceHandler.cs and PackagesResourceHandler.cs provide immediate project visibility for AI agents.

Frequently Asked Questions

What protocols does Unity MCP use for communication?

Unity MCP uses TCP/IP for primary messaging between the TypeScript client and Unity C# server, with JSON as the serialization format. It optionally supports UDP broadcast discovery via the StartUdpListener method in McpServer.cs, allowing clients to automatically detect the editor's IP address without manual configuration.

How do I create a custom command handler in Unity MCP?

Create a class implementing IMcpCommandHandler from Editor/Core/IMcpCommandHandler.cs, define a unique CommandPrefix, and implement the Execute method to return a JObject with status and result fields. Place the file in any Editor folder; the discovery system in McpHandlerDiscovery.cs will automatically register it. For explicit control, manually register instances via McpEditorInitializer.Instance.Server.RegisterHandler().

Is Unity MCP safe to use with production Unity projects?

Unity MCP includes several safety mechanisms: handlers can be individually disabled via McpSettings.cs, all Unity API calls are marshaled to the main thread via ExecuteOnMainThread, and the TCP server only listens on localhost by default. However, handlers like CodeExecutionCommandHandler.cs (shown in samples) demonstrate runtime code execution capabilities, so developers should audit enabled handlers before connecting to external AI services in production environments.

Which AI models are compatible with Unity MCP?

Any AI service that implements the Model Context Protocol specification can interface with Unity MCP, including Anthropic Claude, OpenAI GPT-4, and custom MCP clients. The TypeScript side acts as the MCP client, translating model requests into TCP messages for the Unity server, making the framework agnostic to the specific AI provider as long as they support MCP tool definitions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}