How to Set Up Unity MCP Server (2026)

The Unity MCP Server connects the Unity game engine to AI assistants like Claude, Cursor, and other MCP-compatible tools. This means your AI assistant can directly inspect your Unity scene hierarchy, read component properties, create and modify GameObjects, manage assets, run play mode, and even execute C# scripts -- all through natural language. This guide walks you through the complete setup and practical usage.

What Is Unity MCP Server?

MCP (Model Context Protocol) is an open standard developed by Anthropic for connecting AI assistants to external tools and data sources. The Unity MCP Server implements this protocol specifically for the Unity Editor, exposing Unity's functionality as tools that AI models can call.

What Can It Do?

Capability	Description
Scene Inspection	Read the full scene hierarchy, GameObjects, and components
Object Manipulation	Create, move, rotate, scale, and delete GameObjects
Component Management	Add, remove, and modify components and their properties
Asset Operations	Import, find, and organize project assets
Script Generation	Create and attach C# scripts to GameObjects
Play Mode Control	Start, stop, and pause play mode
Console Reading	Read Unity console logs and errors
Build Management	Trigger builds for target platforms
Prefab Operations	Create and instantiate prefabs
Material Editing	Modify materials, shaders, and textures

Prerequisites

Before setting up the Unity MCP Server, you need:

Unity Editor 2022.3 LTS or later (2023.x or 6000.x also supported)
Node.js 18 or later
Claude Desktop, Claude Code, or Cursor (any MCP-compatible AI client)
A Unity project opened in the editor

Verify Node.js:

node --version
# v18.x.x or later

Step 1: Install the Unity MCP Package

Option A: Via Unity Package Manager (Recommended)

Open your Unity project
Go to Window > Package Manager
Click the + button in the top left
Select Add package from git URL
Enter the package URL:

https://github.com/anthropics/unity-mcp-server.git

Click Add and wait for the installation to complete

Option B: Via manifest.json

Open your project's Packages/manifest.json file and add the dependency:

{
  "dependencies": {
    "com.anthropic.mcp-server": "https://github.com/anthropics/unity-mcp-server.git",
    ...
  }
}

Save the file. Unity will automatically download and install the package.

Option C: Manual Installation

# Clone the repository
git clone https://github.com/anthropics/unity-mcp-server.git

# Copy the package to your project's Packages folder
cp -r unity-mcp-server/package ~/your-unity-project/Packages/com.anthropic.mcp-server

Step 2: Enable the MCP Server in Unity

After installation, enable the server in the Unity Editor:

Go to Edit > Preferences (macOS: Unity > Preferences)
Navigate to MCP Server in the left panel
Toggle Enable MCP Server to On
Note the Port number (default: 6400)
Optionally set an Authentication Token for security

You should see a confirmation in the Unity Console:

[MCP Server] Started on port 6400
[MCP Server] Waiting for connections...

Configuration Options

Setting	Default	Description
Enable MCP Server	Off	Toggle the server on/off
Port	6400	TCP port for MCP connections
Auth Token	(empty)	Optional authentication token
Allow Script Execution	Off	Allow AI to run arbitrary C# code
Allow File Operations	On	Allow AI to create/modify project files
Allow Build Triggers	Off	Allow AI to start builds
Verbose Logging	Off	Log all MCP requests to Unity Console

Security Note: Be cautious with "Allow Script Execution." This lets the AI run arbitrary C# code in your Unity Editor. Only enable it in trusted, local development environments.

Step 3: Configure Your AI Client

Claude Desktop Configuration

Edit your Claude Desktop config file:

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

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/unity-mcp-bridge",
        "--port",
        "6400"
      ]
    }
  }
}

Restart Claude Desktop after saving.

Claude Code Configuration

Add the server to your project or global MCP config:

claude mcp add unity \
  --command "npx" \
  --args "-y" "@anthropic-ai/unity-mcp-bridge" "--port" "6400"

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/unity-mcp-bridge", "--port", "6400"]
    }
  }
}

Cursor Configuration

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/unity-mcp-bridge", "--port", "6400"]
    }
  }
}

Step 4: Verify the Connection

Start a conversation with your AI assistant and test the connection:

Can you see my Unity project? List the GameObjects in the current scene.

If everything is configured correctly, the AI will query Unity and return your scene hierarchy.

Practical Use Cases

1. Scene Setup and Prototyping

Ask the AI to build out a scene layout:

Create a simple platformer level layout:
- A ground plane at (0, 0, 0) scaled to (20, 1, 5)
- 5 floating platforms at varying heights between y=2 and y=8
- A player spawn point at (0, 2, 0) with a red sphere as placeholder
- A goal object at (18, 3, 0) with a green cube and a rotating animation
Add a directional light and set the camera to orthographic view

2. Component Debugging

When something is not working in your game:

I have a "Player" GameObject in my scene. The CharacterController
component does not seem to be detecting collisions with objects
tagged "Enemy". Can you inspect the Player's components and the
Enemy objects to see what might be misconfigured?

3. Automated C# Script Generation

Create a C# script called "CoinCollector" that:
- Detects trigger collisions with objects tagged "Coin"
- Plays a collection sound effect
- Increments a static score counter
- Destroys the coin object
- Updates a UI Text element with the new score
Attach it to the Player GameObject.

The AI generates the script, saves it to your Assets folder, and attaches it to the specified GameObject.

4. Asset Organization

Organize my Assets folder:
- Move all .png and .jpg files into Assets/Art/Textures
- Move all .fbx and .obj files into Assets/Art/Models
- Move all .cs scripts into Assets/Scripts, grouped by namespace
- Move all .wav and .mp3 files into Assets/Audio
Create the folders if they do not exist.

5. Performance Analysis

Enter play mode and monitor the scene for 10 seconds.
Report any console warnings or errors, the approximate frame rate,
and identify any GameObjects with more than 10,000 vertices
in their mesh renderers.

6. Bulk Operations

Find all GameObjects in the scene with a MeshRenderer component
that uses the "Default-Material". Replace their material with
the "StandardPBR" material located in Assets/Materials/.

Available MCP Tools Reference

Here are the key tools exposed by the Unity MCP Server:

unity_get_scene_hierarchy    - Get the full scene tree
unity_get_gameobject         - Get details of a specific GameObject
unity_create_gameobject      - Create a new GameObject
unity_delete_gameobject      - Delete a GameObject
unity_set_transform          - Set position, rotation, scale
unity_add_component          - Add a component to a GameObject
unity_remove_component       - Remove a component
unity_set_component_property - Modify a component property
unity_find_assets            - Search project assets
unity_create_script          - Create a new C# script file
unity_attach_script          - Attach a script to a GameObject
unity_enter_play_mode        - Start play mode
unity_exit_play_mode         - Stop play mode
unity_read_console           - Read console log entries
unity_execute_code           - Run arbitrary C# in the editor
unity_create_prefab          - Create a prefab from a GameObject
unity_instantiate_prefab     - Instantiate a prefab in the scene
unity_set_material           - Assign a material to a renderer
unity_trigger_build          - Start a build for a target platform

Troubleshooting

Issue	Solution
"Cannot connect to Unity"	Verify the MCP Server is enabled in Unity Preferences and the port matches your config
"Port 6400 already in use"	Change the port in both Unity Preferences and your AI client config
AI cannot see scene changes	Ensure Unity Editor is in the foreground; some operations require focus
Scripts fail to compile	Check the Unity Console for C# compilation errors after script creation
"Permission denied" errors	Enable the relevant permission (File Operations, Script Execution) in Unity MCP settings
Slow responses	Large scenes with thousands of objects may take time to serialize; try querying specific objects instead of the full hierarchy

Security Best Practices

Use auth tokens in production. Set an authentication token in Unity MCP Preferences and include it in your client config.
Disable script execution by default. Only enable it when you specifically need the AI to write and run C# code.
Do not expose the port to the network. The MCP server should only accept connections from localhost unless you are working in a secured team environment.
Review AI-generated scripts before running. Even with the best AI, always read generated C# code before attaching it to your project.

Conclusion

The Unity MCP Server transforms the game development workflow by giving your AI assistant direct access to the Unity Editor. Instead of describing your scene in text and pasting code back and forth, you can have Claude or Cursor work directly in your project -- inspecting objects, generating scripts, and validating changes in real time.

For game developers who need AI-generated visual assets -- character animations, cutscene videos, voice acting, or promotional content -- Hypereal AI offers affordable API access to AI video generation, talking avatars, image creation, and voice cloning that can accelerate your game development pipeline.