Unity MCP — AI Assistant Integration for Unity Editor

Unity-native Model Context Protocol (MCP) server for AI-powered game development. Connect Claude, Codex, Cursor, and other AI assistants directly to the Unity Editor — no Node.js, Python, or external runtimes required. Install the package and start building.

New in v2.2

Canvas UI building tools, Input Action management, Project Settings management, batch execution, and merged vision capture.

Features

• 100% Unity-native — Runs entirely inside the Unity Editor as a single package. No sidecar processes to install or maintain.

• Zero telemetry — Completely private. No data leaves your machine.

• 51 built-in tools — Create GameObjects, run tests, build projects, manage scenes, build Canvas UIs, manage input actions, and more.

• 23 resources + 6 resource templates — Read-only access to project settings, scene state, console output, and more via URI patterns.

• 4 workflow prompts — Pre-built prompt templates for common Unity tasks.

• 4 built-in recipes — One-call scene setup templates (FPS prototype, UI canvas, 3D template, physics playground).

• Checkpoint system — Save and restore scene state before destructive operations, with diff support.

• Vision capture — Send Game/Scene View screenshots directly to AI assistants for visual analysis.

• Scene diagnostics — Narrative scene summaries and structured issue scanning in one call.

• Remote access — Connect from other devices on your network with TLS encryption and API key authentication.

• Activity log — Monitor MCP requests and responses in real time from the editor window.

• Per-action annotations — Safety hints (readOnlyHint, destructiveHint) resolved per action, so AI assistants get accurate signals even for multi-action tools.

• Simple extension API — Add custom tools, resources, prompts, and recipes with a single C# attribute.

Requirements

• Unity 2022.3 or later (including Unity 6)

• Any MCP-compatible AI client: Claude Code, Claude Desktop, Codex, Cursor, or others

Installation

1. Open Unity Package Manager (Window > Package Manager)

2. Click + > Add package from git URL

3. Enter the URL for the version you want

Latest version (recommended)

https://github.com/Bluepuff71/UnityMCP.git?path=/Package

Specific version

Append a #version tag to pin to a release:

https://github.com/Bluepuff71/UnityMCP.git?path=/Package#2.2.0

See Releases for available versions.

Setup

Claude Code

claude mcp add unity-mcp --transport http http://localhost:8080/

Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unity-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8080/"]
    }
  }
}

Restart Claude Desktop after saving.

Other MCP clients (Codex, Cursor, etc.)

Unity MCP exposes a built-in HTTP server at http://localhost:8080/. Any MCP-compatible client with HTTP transport support can connect directly. For stdio-only clients, use the mcp-remote bridge as shown above.

Note: Configurations for clients other than Claude Code have not been tested. Open a PR!

Configuration

Editor window

Open the Unity MCP control panel from Window > Unity MCP:

The editor window has four tabs:

• Status — Start/stop the server, view the endpoint URL (with copy button), see tool/resource/prompt/recipe counts, configure the port, and manage remote access settings.

• Activity — Live feed of MCP requests with timestamps, status indicators, and expandable detail panels showing arguments and response metadata.

• Registry — Searchable catalog of all registered tools, resources, prompts, and recipes. Organized by category with annotation badges and expandable parameter details.

• Checkpoints — Browse saved checkpoints, restore or diff scene state, view tracked assets, and check bucket status.

Port

The default port is 8080. To change it:

1. Stop the server.

2. Enter a new port number in the Status tab.

3. Click Apply.

4. Start the server.

Verbose logging

Toggle Verbose Logging in the editor window to enable detailed debug output in the Unity Console. Useful for troubleshooting connection or tool execution issues.

Remote access

Enable remote access to allow AI assistants to connect from other devices on your network:

• Toggle remote access in the Status tab to bind to all network interfaces (0.0.0.0).

• TLS required — Unity MCP auto-generates a self-signed certificate for secure connections.

• API key authentication — A key with the prefix umcp_ is auto-generated on first enable and required for all remote requests.

• Copy or regenerate the API key directly from the editor window.

• Endpoint changes to https://<LAN_IP>:<port>/ when remote access is enabled.

• Certificate storage — Stored in LocalApplicationData/UnityMCP/. Auto-regenerates if your LAN IP changes.

• Firewall — You may need to allow incoming connections on the configured port. This is your responsibility.

Claude Code remote setup

claude mcp add unity-mcp --transport http --header "Authorization: Bearer <API_KEY>" https://<LAN_IP>:8080/

Replace <API_KEY> with your generated key and <LAN_IP> with your Unity machine's IP address.

Available MCP Tools

51 built-in tools organized by category:

[!Tip] Use search_tools with no arguments for a category overview, or pass a query or category to narrow results. Use get_unity_guide for workflow guidance and tool-chaining recipes.

Scene (8)

GameObject (2)

Component (1)

Asset (6)

VFX (1)

Build & Testing (2)

Editor (7)

Console & Profiling (2)

UI Toolkit (6)

Guide & Diagnostics (2)

Export (1)

Recipes (2)

Canvas UI (4)

Input (1)

Search (1)

Utility (1)

Debug (4)

Available MCP Resources

23 built-in resources and 6 resource templates provide read-only access to Unity Editor state via URI patterns:

Scene

• scene://loaded — All currently loaded scenes and their status

Editor

• editor://state — Current editor state (play mode, compiling, focus, etc.)

• editor://selection — Currently selected objects in the editor

• editor://windows — Open editor windows and their states

• editor://prefab_stage — Current prefab editing stage information

• editor://active_tool — Currently active editor tool (Move, Rotate, Scale, etc.)

Project

• project://info — Project path, name, and Unity version

• project://tags — Project tags

• project://layers — Project layers and their indices

• project://player_settings — Player settings including icons, resolution, and platform settings

• project://quality — Quality settings and all quality levels

• project://physics — Physics settings including gravity, solver iterations, and layer collision matrix

• project://audio — Audio settings including speaker mode, DSP buffer, and sample rate

• project://input — Input system actions and bindings, or legacy input axes

• project://rendering — Rendering settings including render pipeline, ambient lighting, and fog

Build & Packages

• build://settings — Build target, scenes, and configuration

• packages://installed — Installed packages and their versions

Console & Tests

• console://summary — Error/warning/info counts from the console

• console://errors — Detailed compilation/runtime errors with file paths and line numbers

• tests://list — Available unit tests

• profiler://state — Profiler recording status and configuration

Menu

• menu://items — Available Unity Editor menu items

UI

• ui://unitymcp/scene-preview.html — Scene preview widget HTML for inline display

Resource Templates

These use URI parameters to query specific objects:

• scene://gameobject/{id} — GameObject details by instance ID

• scene://gameobject/{id}/components — List of components on a GameObject

• scene://gameobject/{id}/component/{type} — Specific component details on a GameObject

• tests://list/{mode} — Tests filtered by mode (EditMode or PlayMode)

• animation://controller/{path} — AnimatorController details including layers, parameters, and state machines

• assets://dependencies/{path} — Asset dependencies — what an asset uses and what uses it

Available MCP Prompts

4 built-in prompt templates for common Unity workflows:

• read_gameobject — Inspect a GameObject's transform, components, and optionally its children

  • name (required) — Name of the GameObject to inspect

  • include_children — Whether to include the children hierarchy (true/false)

• inspect_prefab — Examine a prefab asset by path

  • path (required) — Path to the prefab asset (e.g., Assets/Prefabs/Player.prefab)

• modify_component — Step-by-step guide to safely change a component property

  • target (required) — Name or path of the target GameObject

  • component (required) — Component type to modify (e.g., Rigidbody, BoxCollider)

  • property (required) — Property to modify (e.g., mass, isTrigger)

• setup_scene — Set up a new scene with appropriate defaults for 3D, 2D, or UI

  • scene_type — Type of scene: 3d, 2d, or ui (default: 3d)

Available Recipes

4 built-in scene setup recipes:

• fps_prototype — Creates a basic FPS prototype scene with player capsule, ground plane, directional light, and camera at eye height

  • ground_size — Ground plane size (10–1000, default: 100)

• ui_canvas — Creates a Canvas with EventSystem and a 3-panel layout (header, content, footer)

• 3d_scene_template — Creates a basic 3D scene with directional light, ground plane, and camera positioned at (0, 5, -10)

• physics_playground — Creates a physics playground with a ground plane, three ramps (15°/30°/45°), five spheres, and three cubes — all with Rigidbodies

Architecture

Unity MCP is entirely self-contained within the Unity Editor. A native C plugin runs the HTTP server on a background thread and persists across Unity domain reloads, so the AI assistant connection stays active even while Unity recompiles scripts. No external processes, runtimes, or sidecar applications are needed.

┌─────────────────┐
│  MCP Client     │
│  (Claude, etc.) │
└────────┬────────┘
         │ HTTP(S) POST (JSON-RPC)
         ▼
┌─────────────────────────────────────┐
│  Proxy Plugin (C)                   │
│  - HTTP server on background thread │
│  - Persists across domain reloads   │
│  - Buffers request, waits for       │
│    response from C#                 │
└────────┬────────────────────────────┘
         │ Polling (EditorApplication.update)
         ▼
┌─────────────────────────────────────┐
│  Unity C# (main thread)             │
│  - Compilation gate: defers         │
│    requests while isCompiling       │
│  - Routes to MCPServer handlers     │
│  - Executes tools, reads resources  │
│                                     │
│  Services:                          │
│  - CheckpointManager (scene state)  │
│  - RecipeRegistry (scene templates) │
│  - UISchema (Canvas UI definitions) │
│  - Response dedup cache (defense)   │
└─────────────────────────────────────┘

During script recompilation, the C# compilation gate defers request consumption until the domain reload completes. The AI assistant sees a brief delay rather than a disconnection.

Extending Unity MCP

There are two ways to define tools: an action-based tool for grouping related operations under one tool name, and a single-method tool for standalone operations.

Action-based tools (recommended for related operations)

Place [MCPTool] on a static class and [MCPAction] on each action method. The framework generates a unified JSON schema with a required action enum parameter.

using UnityEditor;
using UnityMCP.Editor;
using UnityEngine;

[MCPTool("enemy_manager", "Manage enemies in the scene", Category = "Gameplay")]
public static class EnemyManagerTool
{
    [MCPAction("spawn", Description = "Spawn an enemy at a position",
        DestructiveHint = true)]
    public static object Spawn(
        [MCPParam("type", "Enemy type", required: true,
            Enum = new[] { "goblin", "skeleton", "dragon" })] string type,
        [MCPParam("x", "X position", required: true)] float x,
        [MCPParam("y", "Y position", required: true)] float y,
        [MCPParam("z", "Z position", required: true)] float z)
    {
        GameObject enemy = new GameObject($"Enemy_{type}");
        enemy.transform.position = new Vector3(x, y, z);
        return new { instanceID = enemy.GetInstanceID(), type };
    }

    [MCPAction("list", Description = "List all enemies in the scene",
        ReadOnlyHint = true)]
    public static object List()
    {
        var enemies = GameObject.FindGameObjectsWithTag("Enemy");
        return new { count = enemies.Length };
    }

    [MCPAction("despawn", Description = "Remove an enemy from the scene",
        DestructiveHint = true)]
    public static object Despawn(
        [MCPParam("instance_id", "Instance ID of the enemy to remove",
            required: true)] int instanceId)
    {
        var target = EditorUtility.InstanceIDToObject(instanceId) as GameObject;
        if (target == null) return new { success = false, error = "Enemy not found." };
        Object.DestroyImmediate(target);
        return new { success = true };
    }
}

Annotation resolution for action-based tools:

• destructiveHint = true if any action has DestructiveHint = true

• readOnlyHint = true only if all actions have ReadOnlyHint = true

The server uses per-action metadata to tell AI assistants which specific actions warrant a checkpoint before proceeding, rather than flagging the entire tool.

Single-method tools (for standalone operations)

Place [MCPTool] directly on a static method:

using UnityMCP.Editor;
using UnityEngine;

public static class MyCustomTools
{
    [MCPTool("hello_world", "Says hello to the specified name")]
    public static string SayHello(
        [MCPParam("name", "Name to greet", required: true)] string name)
    {
        return $"Hello, {name}!";
    }

    [MCPTool("spawn_enemy", "Spawn an enemy at a position with difficulty scaling",
        Category = "Gameplay", DestructiveHint = true)]
    public static object SpawnEnemy(
        [MCPParam("enemy_type", "Type of enemy to spawn", required: true,
            Enum = new[] { "goblin", "skeleton", "dragon" })] string enemyType,
        [MCPParam("x", "X position", required: true)] float x,
        [MCPParam("y", "Y position", required: true)] float y,
        [MCPParam("z", "Z position", required: true)] float z,
        [MCPParam("difficulty", "Difficulty multiplier (1–10)",
            Minimum = 1, Maximum = 10)] float difficulty = 5)
    {
        GameObject enemy = new GameObject($"Enemy_{enemyType}");
        enemy.transform.position = new Vector3(x, y, z);

        return new
        {
            instanceID = enemy.GetInstanceID(),
            type = enemyType,
            difficulty
        };
    }
}

Tools are automatically discovered on domain reload. No registration needed.

Tool annotations

Set annotations on [MCPTool] for single-method tools, or on [MCPAction] for per-action accuracy on action-based tools.

Parameter constraints

Constraints are included in the JSON Schema sent to AI assistants:

Resources expose read-only data to AI assistants via URI patterns. Use [MCPResource]:

using UnityMCP.Editor;
using UnityEngine;

public static class MyCustomResources
{
    [MCPResource("unity://player/stats", "Current player statistics")]
    public static object GetPlayerStats()
    {
        var player = GameObject.Find("Player");
        if (player == null)
            return new { error = "Player not found" };

        return new
        {
            position = player.transform.position,
            health = player.GetComponent<Health>()?.CurrentHealth ?? 0,
            isGrounded = player.GetComponent<CharacterController>()?.isGrounded ?? false
        };
    }
}

Resources are read via resources/read using their URI (e.g., unity://player/stats). They are automatically discovered on domain reload.

Prompts provide reusable workflow templates for AI assistants. Use [MCPPrompt]:

using System.Collections.Generic;
using UnityMCP.Editor;
using UnityMCP.Editor.Core;

public static class MyCustomPrompts
{
    [MCPPrompt("debug_gameobject", "Debug a GameObject by inspecting its state")]
    public static PromptResult DebugGameObject(
        [MCPParam("name", "Name of the GameObject to debug", required: true)] string name,
        [MCPParam("verbose", "Include full component details (true/false)")] string verbose = "false")
    {
        bool isVerbose = verbose?.ToLower() == "true";

        string instructions = $@"Debug the GameObject ""{name}"" using these steps:

1. Use `find_gameobject` with search_term=""{name}"" to locate it
2. Use `manage_component` with action=""inspect"" to check each component";

        if (isVerbose)
        {
            instructions += $@"
3. Use `read_console` with filter=""{name}"" to check for related log messages";
        }

        return new PromptResult
        {
            description = $"Debug instructions for '{name}'",
            messages = new List<PromptMessage>
            {
                new PromptMessage
                {
                    role = "user",
                    content = new PromptMessageContent
                    {
                        type = "text",
                        text = instructions
                    }
                }
            }
        };
    }
}

Recipes are reusable scene setup templates invoked via execute_recipe. Use [MCPRecipe] on a static method:

using UnityMCP.Editor;

public static class MyRecipes
{
    [MCPRecipe("my_scene_setup", "Creates a custom scene layout")]
    public static object MySceneSetup(
        [MCPParam("size", "World size", Minimum = 10, Maximum = 500)] float size = 50)
    {
        // Create your scene objects here...
        return new { success = true, summary = "Scene created" };
    }
}

Recipes are automatically discovered on domain reload and appear in list_recipes output.

License

GPLv3 — see the LICENSE file for details.