Unity MCP Integration

You connect a Unity project to an MCP client to access real-time project data, edit files, run editor code, and monitor the Unity Editor from the MCP ecosystem. This server enables secure, targeted interactions with Unity—letting AI assistants understand your scene, inspect assets, and execute C# in the Editor while keeping your project safe and organized.

How to use

You will run the Unity MCP server locally and connect an MCP client to it. Once connected, you can browse and manipulate project files, inspect the scene hierarchy, execute C# in the Unity Editor, read logs, and control the Editor’s play mode. Use the MCP Debug window in Unity to verify the connection, test commands, and observe logs in real time.

How to install

Prerequisites you need before starting: Unity 2021.3 or later and Node.js 18+. These ensure you can run the Unity project alongside the MCP server.

Option A: Run the MCP server directly from the Unity package cache.

1. Open your project and locate the Unity MCP package cache path, typically under Library/PackageCache/com.quaza.unitymcp@<version>/mcpServer/.

2. Install dependencies.

npm install

How to install

3. Start the MCP server.

node build/index.js

Option B: Add to MCP Host configuration

If you manage MCP clients via a central MCP Host, add this server configuration to the host settings.

{
  "mcpServers": {
    "unity-mcp-server": {
      "command": "node",
      "args": [
        "path-to-project>\\Library\\PackageCache\\com.quaza.unitymcp@d2b8f1260bca\\mcpServer\\mcpServer\\build\\index.js"
      ],
      "env": {
        "MCP_WEBSOCKET_PORT": "5010"
      }
    }
  }
}

Demo and auto-install options

If you prefer automatic installation for Claude Desktop or other MCP clients, you can install the Unity MCP Integration package via Smithery.

npx -y @smithery/cli install @quazaai/unitymcpintegration --client claude

Usage notes

After installation, you can access a variety of tools to interact with Unity. Ensure your Unity Editor is running and the MCP server is reachable via the configured port. Use the MCP Debug window in Unity to verify connectivity, test code execution, and monitor logs.

Additional considerations

Architecture: The integration uses a Unity Plugin (C#) in the Editor and an MCP Server (TypeScript/Node.js) that communicates over WebSocket with JSON messages. File system access is constrained to your Unity project directory for security.

Security: Ensure you run the MCP server on a trusted host and limit access to your local network or secure environments. Use strong, unique ports and monitor connection activity via the Unity MCP Debug window.

Troubleshooting: If the MCP client cannot connect, verify that the MCP_WEBSOCKET_PORT matches your host configuration and that the Node.js server is running. Check Unity console logs for errors related to the MCP plugin.

Notes on filesystem access and editing

The Unity MCP integration provides filesystem tools to read, edit, and list files within your project. All file operations are scoped to the Assets folder to protect your project integrity. Use the file tools to inspect scenes, assets, scripts, and configuration files, or to apply targeted edits with preview diffs.

Available tools

get_editor_state

Retrieve comprehensive information about the Unity project and current editor state.

get_current_scene_info

Fetch detailed data about the active scene, including game objects and components.

get_game_objects_info

Obtain information about specific GameObjects in the scene.

execute_editor_command

Execute C# code directly inside the Unity Editor context.

get_logs

Access and filter Unity console logs for debugging and monitoring.

verify_connection

Check the active connection status between the MCP server and Unity Editor.

read_file

Read the contents of a file within the Unity project.

read_multiple_files

Read multiple files in a single request.

write_file

Create or overwrite a file with new content in the Unity project.

edit_file

Apply targeted edits to existing files with a diff preview.

list_directory

List files and folders in a specified directory.

directory_tree

Provide a hierarchical view of directories and files.

search_files

Search for files matching a pattern across the project.

get_file_info

Get metadata about a specific file or directory.

find_assets_by_type

Find all assets of a given type, such as Material or Prefab.

list_scripts

List all C# scripts contained in the project.