Unity MCP Server

Unity MCP Server

A Model Context Protocol (MCP) server plugin for Unity Editor that exposes project context to AI coding agents like Claude, Cursor, Copilot, and others.

Features

Read Operations

• Full Scene Hierarchy Access: Query GameObjects, their components, and properties
• Component Inspection: Read all serialized fields with values, types, and tooltips
• Script Analysis: List and read MonoBehaviour/ScriptableObject scripts with field and method information
• Project Settings: Access PlayerSettings, QualitySettings, Physics, Tags/Layers, Input, Graphics, and Build settings
• Asset Database: Search and query assets by type, folder, or name with type-specific metadata
• Asset Dependencies: Inspect dependency graphs for any asset
• Folder Structure: Browse the project folder hierarchy
• Package Manager: List all installed UPM packages
• Animation Inspection: Read animation clips (curves, keyframes, events) and animator controllers (layers, states, transitions, parameters)
• Project Info: Query runtime project information (product name, Unity version, platform, etc.)

Write Operations (Opt-in)

• GameObject Manipulation: Create, delete, rename, move, duplicate GameObjects
• Component Management: Add, remove, enable/disable components
• Property Editing: Modify component properties and serialized fields
• Object Reference Assignment: Programmatic drag-and-drop equivalent for Inspector fields
• Transform Control: Set position, rotation, scale
• Prefab Operations: Create prefabs from GameObjects, instantiate prefabs
• Scene Management: Save scenes
• Animation Authoring: Create/edit animation clips, curves, keyframes, and events
• Animator Controller Authoring: Create controllers, add states, transitions, parameters, and layers
• Editor Commands: Execute safe C# expressions (sandboxed)

All mutations support Unity's Undo system (Ctrl+Z).

Project Structure

com.unityai.mcp/
├── Editor/
│   ├── Handlers/
│   │   ├── AnimationHandler.cs      # Animation clip & animator controller tools
│   │   ├── AssetHandler.cs          # Asset search, packages, dependencies, folders
│   │   ├── ComponentHandler.cs      # Component serialization & inspection
│   │   ├── EditorCommandHandler.cs  # Sandboxed C# expression execution
│   │   ├── HierarchyHandler.cs      # Scene hierarchy & GameObject queries
│   │   ├── MutationHandler.cs       # All write operations (GameObjects, components, prefabs)
│   │   ├── ProjectSettingsHandler.cs# Unity project settings reader
│   │   └── ScriptHandler.cs         # Script listing & source reading
│   ├── Transport/
│   │   ├── HttpTransport.cs         # HTTP/SSE server & JSON-RPC transport
│   │   └── StdioTransport.cs        # Stdio transport & JSON-RPC message types
│   ├── Utils/
│   │   └── SerializationHelper.cs   # Unity type serialization & JSON parser
│   ├── UnityMCPServer.cs            # Main server, MCP protocol, tool routing
│   ├── UnityMCPEditorWindow.cs      # Editor UI (Window > Unity MCP)
│   └── com.unityai.mcp.Editor.asmdef
├── package.json
├── mcp_config.json
├── CHANGELOG.md
└── README.md

Requirements

• Unity 2022.3 LTS or newer (including Unity 6.x)
• Windows, macOS, or Linux

Installation

Option 1: Git URL (Recommended)

1. Open Unity Package Manager (Window > Package Manager)
2. Click the "+" button and select "Add package from git URL..."
3. Enter: https://github.com/coolmew/Unity-MCP.git

Option 2: Local Package

1. Clone or download this repository
2. Copy the com.unityai.mcp folder to your project's Packages/ directory
3. Unity will automatically detect and import the package

Option 3: Embedded Package

1. Copy the entire com.unityai.mcp folder into your project's Packages/ folder
2. The package will be embedded in your project

Quick Start

1. After installation, the MCP server starts automatically with Unity
2. Open Window > Unity MCP to see the server status and settings
3. Copy the MCP configuration to your AI client
4. Start querying your Unity project!

Connecting AI Clients

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unity": {
      "url": "http://localhost:6400/mcp",
      "transport": "http"
    }
  }
}

Cursor / Windsurf

Add to your MCP settings:

{
  "mcpServers": {
    "unity": {
      "url": "http://localhost:6400/mcp",
      "transport": "http"
    }
  }
}

Custom HTTP Client

Send JSON-RPC 2.0 requests to http://localhost:6400/rpc:

curl -X POST http://localhost:6400/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Available Tools

Read Tools

getSceneHierarchy

Returns the full scene hierarchy with all