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

> Discover Unity MCP an open-source Unity Editor extension that integrates AI language models into your projects via TCP/IP for command execution resource querying and more

- Repository: [いすず/unitymcp](https://github.com/isuzu-shiranui/unitymcp)
- Tags: getting-started
- Published: 2026-03-04

---

**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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/AssembliesResourceHandler.cs) and [`PackagesResourceHandler.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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:

```csharp
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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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:

```typescript
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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpServer.cs), routes it to the `HelloWorldHandler`, and returns:

```json
{
  "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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpHandlerDiscovery.cs) eliminates manual registration; place handler files in Editor folders and they register automatically.
- **Thread safety** is enforced through `ExecuteOnMainThread` in [`McpServer.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpServer.cs), ensuring all Unity API calls occur on the main editor thread.
- **Built-in handlers** like [`AssembliesResourceHandler.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/AssembliesResourceHandler.cs) and [`PackagesResourceHandler.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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.