README

Proudly sponsored and maintained by Coplay -- the best AI assistant for Unity.

Create your Unity apps with LLMs! MCP for Unity bridges AI assistants (Claude, Claude Code, Cursor, VS Code, etc.) with your Unity Editor via the Model Context Protocol. Give your LLM the tools to manage assets, control scenes, edit scripts, and automate tasks.

• v9.6.3 (beta) — New manage_profiler tool (14 actions): Profiler session control (start/stop/status/set areas), frame timing and counter reads, object memory queries, memory snapshots (take/list/compare via com.unity.memoryprofiler), and Frame Debugger (enable/disable/get events). Group: profiling.
• v9.6.2 — New manage_physics tool (21 actions): physics settings, layer collision matrix, physics materials, joints (5 3D + 9 2D types), queries (raycast, raycast_all, linecast, shapecast, overlap), force application (AddForce/AddTorque/AddExplosionForce), rigidbody configuration, scene-wide validation, and edit-mode simulation. Full 3D and 2D support.
• v9.6.1 — QoL extensions: manage_editor gains undo/redo actions. manage_scene gains multi-scene editing (additive load, close, set active, move GO between scenes), scene templates (3d_basic, 2d_basic, etc.), and scene validation with auto-repair. New manage_build tool: trigger player builds, switch platforms, configure player settings, manage build scenes and profiles (Unity 6+), run batch builds across multiple platforms, and async job tracking with polling. New MaxPollSeconds infrastructure for long-running tool operations.
• v9.5.4 — New unity_reflect and unity_docs tools for API verification: inspect live C# APIs via reflection and fetch official Unity documentation (ScriptReference, Manual, package docs). New manage_packages tool: install, remove, search, and manage Unity packages and scoped registries. Includes input validation, dependency checks on removal, and git URL warnings.
• v9.5.3 — New manage_graphics tool (33 actions): volume/post-processing, light baking, rendering stats, pipeline settings, URP renderer features. 3 new resources: volumes, rendering_stats, renderer_features.
• v9.5.2 — New manage_camera tool with Cinemachine support (presets, priority, noise, blending, extensions), cameras resource, priority persistence fix via SerializedProperty.

• v9.4.8 — New editor UI, real-time tool toggling via manage_tools, skill sync window, multi-view screenshot, one-click Roslyn installer, Qwen Code & Gemini CLI clients, ProBuilder mesh editing via manage_probuilder.
• v9.4.7 — Per-call Unity instance routing, macOS pyenv PATH fix, domain reload resilience for script tools.
• v9.4.6 — New manage_animation tool, Cline client support, stale connection detection, tool state persistence across reloads.
• v9.4.4 — Configurable batch_execute limits, tool filtering by session state, IPv6/IPv4 loopback fixes.

Quick Start

Prerequisites

• Unity 2021.3 LTS+ — Download Unity
• Python 3.10+ and uv — Install uv
• An MCP Client — Claude Desktop | Claude Code | Cursor | VS Code Copilot | GitHub Copilot CLI | Windsurf

1. Install the Unity Package

In Unity: Window > Package Manager > + > Add package from git URL...

[!TIP]

textCopy

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

Want the latest beta? Use the beta branch:

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#beta

Unity Asset Store:

1. Visit MCP for Unity on the Asset Store
2. Click Add to My Assets, then import via Window > Package Manager

OpenUPM:

openupm add com.coplaydev.unity-mcp

2. Start the Server & Connect

1. In Unity: Window > MCP for Unity
2. Click Start Server (launches HTTP server on localhost:8080)
3. Select your MCP Client from the dropdown and click Configure
4. Look for 🟢 "Connected ✓"
5. Connect your client: Some clients (Cursor, Windsurf, Antigravity) require enabling an MCP toggle in settings, while others (Claude Desktop, Claude Code) auto-connect after configuration.

That's it! Try a prompt like: "Create a red, blue and yellow cube" or "Build a simple player controller"

Key Features

• Natural Language Control — Instruct your LLM to perform Unity tasks
• Powerful Tools — Manage assets, scenes, materials, scripts, and editor functions
• Automation — Automate repetitive Unity workflows
• Extensible — Works with various MCP Clients

Available Tools

apply_text_edits • batch_execute • create_script • debug_request_context • delete_script • execute_custom_tool • execute_menu_item • find_gameobjects • find_in_file • get_sha • get_test_job • manage_animation • manage_asset • manage_build • manage_camera • manage_components • manage_editor • manage_gameobject • manage_graphics • manage_material • manage_packages • manage_physics • manage_prefabs • manage_probuilder • manage_profiler • manage_scene • manage_script • manage_script_capabilities • manage_scriptable_object • manage_shader • manage_texture • manage_tools • manage_ui • manage_vfx • read_console • refresh_unity • run_tests • script_apply_edits • set_active_instance • unity_docs • unity_reflect • validate_script

Available Resources

cameras • custom_tools • renderer_features • rendering_stats • volumes • editor_active_tool • editor_prefab_stage • editor_selection • editor_state • editor_windows • gameobject • gameobject_api • gameobject_component • gameobject_components • get_tests • get_tests_for_mode • menu_items • prefab_api • prefab_hierarchy • prefab_info • project_info • project_layers • project_tags • tool_groups • unity_instances

Performance Tip: Use batch_execute for multiple operations — it's 10-100x faster than individual calls!

If auto-setup doesn't work, add this to your MCP client's config file:

HTTP (default — works with Claude Desktop, Cursor, Windsurf):

{
  "mcpServers": {
    "unityMCP": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

VS Code:

{
  "servers": {
    "unityMCP": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "unityMCP": {
      "command": "uvx",
      "args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "unityMCP": {
      "command": "C:/Users/YOUR_USERNAME/AppData/Local/Microsoft/WinGet/Links/uvx.exe",
      "args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
    }
  }
}

MCP for Unity supports multiple Unity Editor instances. To target a specific one:

1. Ask your LLM to check the unity_instances resource
2. Use set_active_instance with the Name@hash (e.g., MyProject@abc123)
3. All subsequent tools route to that instance

For Strict validation that catches undefined namespaces, types, and methods:

1. Install NuGetForUnity
2. Window > NuGet Package Manager → Install Microsoft.CodeAnalysis v5.0
3. Also install SQLitePCLRaw.core and SQLitePCLRaw.bundle_e_sqlite3 v3.0.2
4. Add USE_ROSLYN to Player Settings > Scripting Define Symbols
5. Restart Unity

Open Window > MCP for Unity, scroll to the Runtime Code Execution (Roslyn) section in the Scripts/Validation tab, and click Install Roslyn DLLs. This downloads the required NuGet packages and places the DLLs in Assets/Plugins/Roslyn/ automatically.

You can also run it from the menu: Window > MCP For Unity > Install Roslyn DLLs.

1. Download Microsoft.CodeAnalysis.CSharp.dll and dependencies from NuGet
2. Place DLLs in Assets/Plugins/Roslyn/ folder
3. Ensure .NET compatibility settings are correct
4. Add USE_ROSLYN to Scripting Define Symbols
5. Restart Unity

• Unity Bridge Not Connecting: Check Window > MCP for Unity status, restart Unity
• Server Not Starting: Verify uv --version works, check the terminal for errors
• Client Not Connecting: Ensure the HTTP server is running and the URL matches your config

Detailed setup guides:

• Fix Unity MCP and Cursor, VSCode & Windsurf — uv/Python installation, PATH issues
• Fix Unity MCP and Claude Code — Claude CLI installation
• Common Setup Problems — macOS dyld errors, FAQ

Still stuck? Open an Issue or Join Discord

See README-DEV.md for development setup. For custom tools, see CUSTOM_TOOLS.md.

1. Fork → Create issue → Branch (feature/your-idea) → Make changes → PR

Anonymous, privacy-focused telemetry (no code, no project names, no personal data). Opt out with DISABLE_TELEMETRY=true. See TELEMETRY.md.

Network defaults are intentionally fail-closed:

• HTTP Local allows loopback-only hosts by default (127.0.0.1, localhost, ::1).
• Bind-all interfaces (0.0.0.0, ::) require explicit opt-in in Advanced Settings via Allow LAN Bind (HTTP Local).
• HTTP Remote requires https:// by default.
• Plaintext http:// for remote endpoints requires explicit opt-in via Allow Insecure Remote HTTP.

License: MIT — See LICENSE | Need help? Discord | Issues

Star History

@inproceedings{10.1145/3757376.3771417,
author = {Wu, Shutong and Barnett, Justin P.},
title = {MCP-Unity: Protocol-Driven Framework for Interactive 3D Authoring},
year = {2025},
isbn = {9798400721366},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/3757376.3771417},
doi = {10.1145/3757376.3771417},
series = {SA Technical Communications '25}
}

Unity AI Tools by Coplay

Coplay offers 3 AI tools for Unity:

• MCP for Unity is available freely under the MIT license.
• Coplay is a premium Unity AI assistant that sits within Unity and is more than the MCP for Unity.
• Coplay MCP a free-for-now MCP for Coplay tools.

(These tools have different tech stacks. See this blog post comparing Coplay to MCP for Unity.)

Disclaimer

This project is a free and open-source tool for the Unity Editor, and is not affiliated with Unity Technologies.