home / mcp / unity mcp server

Unity MCP Server

Provides an HTTP and local stdio MCP bridge to connect Unity Editor with AI assistants for asset, scene, and script automation.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You can run MCP for Unity to connect an AI assistant to your Unity Editor, enabling natural language control of assets, scenes, scripts, and editor tasks. This server supports multiple MCP clients and provides a streamlined path to automate common Unity workflows through a configurable bridge between your editor and your chosen AI toolset.

How to use

Begin by ensuring you have Unity 2021.3 LTS or newer, Python 3.10+ installed, and an MCP client such as Claude Desktop, Claude Code, Cursor, Windsurf, or similar. Start the Unity MCP server from within Unity, connect your MCP client, and confirm the connection status shows green, indicating an active connection.

Once connected, you can instruct the AI to perform Unity tasks using natural language. Common actions include creating or editing assets, building scenes, scripting, and automating repetitive workflows. If you want to try a simple test, ask the AI to create a basic scene with colored objects or to build a basic player controller. The server routes all subsequent tool calls to the currently selected Unity instance and the active client, so you can switch targets as needed.

How to install

Prerequisites your environment must satisfy before installing MCP for Unity.

Step-by-step installation options are shown below. Choose the method that fits your setup.

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

Additional sections

Manual configuration of the MCP client is supported if auto-setup doesn’t work. You can add a server entry to your MCP client configuration with the HTTP URL shown above or configure the stdio transport for local execution.

Troubleshooting

If the Unity bridge isn’t connecting, open the Unity window for MCP for Unity and verify the server status, then restart Unity if needed. If the server won’t start, check that the uv tool is installed and accessible in your PATH and review the terminal for errors. If a client cannot connect, ensure the HTTP server is running and the configured URL matches. For persistent issues, consult the community Discord or raise an issue with relevant logs.

Contributing and telemetry

Telemetry is anonymous and privacy-focused by default, with an option to opt out. If you enable telemetry, you can disable it by setting DISABLE_TELEMETRY=true in your environment. For contribution guidelines, follow the project’s contribution process to propose enhancements or custom tools.

Security

Network defaults favor security. Local HTTP (loopback) is allowed by default, while bind-all interfaces require explicit opt-in. Remote HTTP endpoints require explicit acceptance of HTTPS and insecure HTTP settings must be opt-in via advanced settings. Always operate MCP servers within trusted networks and review security settings before exposing endpoints.

Roslyn script validation (advanced)

For strict validation that catches undefined namespaces, types, and methods, you can enable Roslyn-based validation by installing the Roslyn tooling and configuring the scripting define symbol USE_ROSLYN in your project. This is an advanced option and requires additional DLLs if NuGet-based tooling is unavailable.

Available tools

apply_text_edits

Apply text edits to scripts or configuration files via the LLM, enabling quick fixes and refinements.

batch_execute

Run multiple tool actions in sequence for efficiency, reducing round-trips to the Unity API.

create_script

Generate new Unity C# scripts based on prompts or templates and integrate them into your project.

debug_request_context

Inspect the current request context to troubleshoot tool calls and ensure correct target objects.

delete_script

Remove an existing script from the Unity project.

execute_custom_tool

Invoke a custom, user-defined tool within the MCP environment.

execute_menu_item

Trigger a Unity editor menu item to perform built-in actions.

find_gameobjects

Search for GameObjects in the active scene or project by name or type.

find_in_file

Locate occurrences of text within a file or set of files.

get_sha

Retrieve a SHA hash for versioning or integrity checks.

get_test_job

Run a test job to validate changes or tooling integration.

manage_animation

Modify or create animation assets and their properties.

manage_asset

Handle asset import, organization, and metadata operations.

manage_components

Add, remove, or configure Unity components on GameObjects.

manage_editor

Operate Unity editor-level settings and preferences programmatically.

manage_gameobject

Modify GameObject properties, hierarchy, and components.

manage_material

Create and edit materials and shaders for rendering.

manage_prefabs

Create, update, or replace prefab assets in your project.

manage_scene

Load, modify, and save scenes, including lighting and objects.

manage_script

Edit, validate, and apply changes to C# scripts.

manage_script_capabilities

Manage script capabilities and metadata for enhanced IDE support.

manage_scriptable_object

Create and manipulate ScriptableObject assets.

manage_shader

Edit shader code and properties to control rendering.

manage_texture

Handle texture assets and their import settings.

manage_vfx

Create and adjust visual effects assets and controllers.

read_console

Read Unity console output for debugging and feedback.

refresh_unity

Refresh Unity to apply changes or reload assets.

run_tests

Execute test suites to validate project changes.

script_apply_edits

Apply scripted edits to code and assets in batch.

set_active_instance

Target a specific Unity Editor instance for subsequent actions.

validate_script

Validate C# scripts for syntax and basic semantic correctness.