Unity MCP Server

Chinese | English

A Unity Editor plugin that exposes Unity Editor capabilities to external AI agents via the MCP (Model Context Protocol).

Agents (such as Kiro, Cursor, or Claude Code) can connect to the Unity Editor via the standard MCP protocol to invoke editor functions.

Philosophy

This plugin is positioned as a Unity perception layer + diagnostic toolchain for AI Agents:

• Perception First — Prioritizes high-frequency scenarios such as "reading scene state, obtaining context, and assisting with diagnostics," allowing Agents to fully understand the current project state and assist in development decisions.

• Structured Writing — Provides safe, auditable write capabilities (e.g., modifying properties, adding/removing nodes), but does not aim to cover all interactions of the Unity Editor GUI.

• Not a Replacement for the Editor — The goal is to enhance the efficiency of collaboration between engineers and Agents, rather than moving all Editor operations into a dialog box.

Related MCP server: MCP Unity

Features

• Streamable HTTP Transport — Based on the MCP 2025-03-26 specification, single HTTP endpoint

• In-Process Execution — No external Node.js/Python processes required; starts directly within the Editor

• Extensible Tool System — Implement the IMcpTool interface to register new tools with zero modifications to core code

• Domain Reload Auto-Recovery — Service automatically restarts after entering/exiting PlayMode

Built-in Tools

For full parameter descriptions and usage examples, see Tool Documentation.

Debug Tools

Editor Tools

Query

Mutation

Project

Asset

Build Tools

Code Tools (Experimental, Unity 2022 Mono only)

Must be manually enabled in the Window → MCP Server panel. See Tool Documentation for details.

Installation

Git URL Installation (Recommended)

1. Unity Editor → Window → Package Manager → + → Add package from git URL

2. Enter the following URL:

https://github.com/yangfch3/Unity-MCP-Server.git

Or edit the host project's Packages/manifest.json directly:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git"
  }
}

Local Path Installation

1. Clone this repository

2. Unity Editor → Window → Package Manager → + → Add package from disk

3. Select the package.json in the root of this repository

Or add to Packages/manifest.json:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "file:../../path/to/unity-mcp"
  }
}

Version Updates

After installing via Git URL, UPM locks the current commit hash in the host project's packages-lock.json. It will not update automatically.

To lock a specific version, append a Git Tag to the end of the URL:

https://github.com/yangfch3/Unity-MCP-Server.git#v0.3.0

Corresponding Packages/manifest.json configuration:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git#v0.3.0"
  }
}

Without a tag, it tracks the latest commit of the default branch:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git"
  }
}

When updating versions, modify the #tag suffix in manifest.json to the new version number, or re-add the package from the git URL with the new tag in the UPM GUI.

Usage

Start Service

1. Unity Editor → Window → MCP Server

2. Set the port (default 8090) and click Start

3. Copy the configuration JSON from the panel

Configure Agent

Add the following content to your Agent's MCP configuration file (e.g., mcp.json):

{
  "mcpServers": {
    "unity-mcp": {
      "url": "http://localhost:8090/"
    }
  }
}

Extension: Adding Custom Tools

Implement the IMcpTool interface and place it in any Editor assembly; the service will automatically discover and register it upon startup:

using System.Collections.Generic;
using System.Threading.Tasks;
using UnityMcp.Editor;

public class MyCustomTool : IMcpTool
{
    public string Name => "my_custom_tool";
    public string Category => "custom";
    public string Description => "我的自定义工具";
    public string InputSchema => "{\"type\":\"object\",\"properties\":{}}";

    public Task<ToolResult> Execute(Dictionary<string, object> parameters)
    {
        return Task.FromResult(ToolResult.Success("Hello from custom tool!"));
    }
}

Requirements

• Unity 2022.3+

• Editor environment only; does not affect runtime builds

Contributing

Contributions to this project are welcome. See CONTRIBUTING.md for details.

License

MIT