Home / MCP / Unity MCP Server

Unity MCP Server

Bridges Unity Editor with AI assistants to control assets, scenes, scripts, and editor state via HTTP or local stdio transport.

python

4.2kstars

View on GitHub

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You connect your MCP client to Unity to control the editor with natural language. This MCP for Unity bridge and server pair lets you issue commands from your preferred AI assistant to manage assets, scenes, scripts, and editor actions inside the Unity Editor, using either HTTP transport or a local stdio bridge.

How to use

Open a Unity project and start the local HTTP server from the MCP panel to establish the HTTP endpoint. Then launch your MCP client (Claude, Cursor, VS Code Copilot, or another supported client) and connect it to that endpoint. Once connected, you can issue natural language prompts to perform Unity tasks across assets, scenes, game objects, scripts, shaders, and editor settings.

If you work with multiple Unity Editor instances, you can route tool calls to a specific instance by selecting it as the active instance through the MCP client. This isolates each session so your prompts affect only the intended Unity window.

Example capabilities you can invoke include creating objects, editing scripts with precise text changes, importing assets, running editor actions, and querying the editor state or selection. Start with simple tasks like creating a red cube, then move to more complex workflows such as building a small scene or implementing a shader and applying it to a material.

How to install

Prerequisites you need before installing the MCP server and bridge: Python 3.10 or newer, Unity Editor (2021.3 LTS or newer), and a compatible MCP client such as Claude, Cursor, or VS Code Copilot. You also need uv, the Python toolchain manager, installed on your platform.

Install uv on your system using the commands below according to your platform.

Step 1 Install the Unity Package

# To install via Git URL
1. Open your Unity project.
2. Window > Package Manager
3. + Add package from git URL
4. https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity
5. Click Add

# Optional fixed version
https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v8.0.0

Step 2 Start the Local HTTP Server (Default)

HTTP transport is enabled by default. Use the Unity MCP window to start the local HTTP server. The Unity window will spawn a separate terminal that runs the server. Keep that terminal open while you work.

Step 3 Configure Your MCP Client

Connect your MCP client to the HTTP server. Auto-setup is recommended for Claude, Cursor, and VS Code Copilot. If auto-setup succeeds, the client saves the HTTP URL and connects automatically.

Step 4 Alternative Client Configuration (Manual)

If auto-setup does not work or you use a different client, manually configure the MCP server endpoint in your client’s configuration file using the HTTP URL shown in Step 2. The client configuration must reference the URL http://localhost:8080/mcp (or the exact URL you configured).

Step 5 Transport options and manual start

If you prefer stdio transport, switch the transport to Stdio in the Unity MCP window. Unity will then use the embedded TCP bridge instead of launching the HTTP server. You can also start the server manually for debugging or CI builds.

Step 6 Multiple Unity instances

To direct tool calls to a specific Unity instance, first list the running instances, then set the active instance using the exact Name@hash shown by the instance list. All subsequent tool calls route to that instance until you switch again.

Step 7 Notes on tooling and validation

The MCP server exposes a broad set of tools to automate Unity tasks, validate scripts, and manage assets and scenes. Use the tools from your MCP client to compose complex workflows, then iterate quickly by validating edits and applying changes atomically.

Troubleshooting

If you encounter connectivity or server startup issues, ensure the Unity Editor is running, the MCP window shows a session, and the local HTTP server process is active. Confirm the server path and that uv is installed and accessible. If necessary, run the server manually from a terminal to observe errors.

Available tools

execute_custom_tool

Execute a project-scoped custom tool registered by Unity.

execute_menu_item

Execute a Unity Editor menu item such as File/Save Project.

manage_asset

Perform asset operations including import, create, modify, or delete assets.

manage_editor

Control and query the editor's state and settings.

manage_gameobject

Create, modify, delete, or query GameObjects and their components.

manage_prefabs

Manage prefab creation, modification, and deletion.

manage_scene

Load, save, create, and inspect scenes and hierarchies.

manage_script

Compatibility router for legacy script operations; prefer edits via apply_text_edits or script_apply_edits.

manage_shader

Create, read, modify, or delete shaders.

read_console

Read messages from or clear the Unity Console.

run_tests

Run tests inside the Unity Editor.

set_active_instance

Route subsequent tool calls to a specific Unity instance by Name@hash.

apply_text_edits

Apply precise text edits with precondition hashes and multi-edit batches.

script_apply_edits

Edit C# methods/classes with safe insert/replace/delete operations.

validate_script

Validate scripts quickly to catch syntax or structural issues before/after edits.

create_script

Create a new C# script at a given project path.

delete_script

Delete a C# script by URI or Assets-relative path.

get_sha

Retrieve SHA256 and basic metadata for a Unity C# script without file contents.