mcp-unity

1507 GitHub stars recorded

IDE Integration - Package Cache Access

MCP Unity provides automatic integration with VSCode-like IDEs (Visual Studio Code, Cursor, Windsurf, Google Antigravity) by adding the Unity Library/PackedCache folder to your workspace. This feature:

• Improves code intelligence for Unity packages
• Enables better autocompletion and type information for Unity packages
• Helps AI coding assistants understand your project's dependencies

MCP Server Tools

The following tools are available for manipulating and querying Unity scenes and GameObjects via MCP:

• execute_menu_item: Executes Unity menu items (functions tagged with the MenuItem attribute)

  Example prompt: "Execute the menu item 'GameObject/Create Empty' to create a new empty GameObject"

• select_gameobject: Selects game objects in the Unity hierarchy by path or instance ID

  Example prompt: "Select the Main Camera object in my scene"

• update_gameobject: Updates a GameObject's core properties (name, tag, layer, active/static state), or creates the GameObject if it does not exist

  Example prompt: "Set the Player object's tag to 'Enemy' and make it inactive"

• update_component: Updates component fields on a GameObject or adds it to the GameObject if it does not contain the component

  Example prompt: "Add a Rigidbody component to the Player object and set its mass to 5"

• add_package: Installs new packages in the Unity Package Manager

  Example prompt: "Add the TextMeshPro package to my project"

• run_tests: Runs tests using the Unity Test Runner

  Example prompt: "Run all the EditMode tests in my project"

• send_console_log: Send a console log to Unity

  Example prompt: "Send a console log to Unity Editor"

• add_asset_to_scene: Adds an asset from the AssetDatabase to the Unity scene

  Example prompt: "Add the Player prefab from my project to the current scene"

• create_prefab: Creates a prefab with optional MonoBehaviour script and serialized field values

  Example prompt: "Create a prefab named 'Player' from the 'PlayerController' script"

• create_scene: Creates a new scene and saves it to the specified path

  Example prompt: "Create a new scene called 'Level1' in the Scenes folder"

• load_scene: Loads a scene by path or name, with optional additive loading

  Example prompt: "Load the MainMenu scene"

• delete_scene: Deletes a scene by path or name and removes it from Build Settings

  Example prompt: "Delete the old TestScene from my project"

• get_gameobject: Gets detailed information about a specific GameObject including all components

  Example prompt: "Get the details of the Player GameObject"

• get_console_logs: Retrieves logs from the Unity console with pagination support

  Example prompt: "Show me the last 20 error logs from the Unity console"

• recompile_scripts: Recompiles all scripts in the Unity project

  Example prompt: "Recompile scripts in my Unity project"

• save_scene: Saves the current active scene, with optional Save As to a new path

  Example prompt: "Save the current scene" or "Save the scene as 'Assets/Scenes/Level2.unity'"

• get_scene_info: Gets information about the active scene including name, path, dirty state, and all loaded scenes

  Example prompt: "What scenes are currently loaded in my project?"

• unload_scene: Unloads a scene from the hierarchy (does not delete the scene asset)

  Example prompt: "Unload the UI scene from the hierarchy"

• duplicate_gameobject: Duplicates a GameObject in the scene with optional renaming and reparenting

  Example prompt: "Duplicate the Enemy prefab 5 times and rename them Enemy_1 through Enemy_5"

• delete_gameobject: Deletes a GameObject from the scene

  Example prompt: "Delete the old Player object from the scene"

• reparent_gameobject: Changes the parent of a GameObject in the hierarchy

  Example prompt: "Move the HealthBar object to be a child of the UI Canvas"

• move_gameobject: Moves a GameObject to a new position (local or world space)

  Example prompt: "Move the Player object to position (10, 0, 5) in world space"

• rotate_gameobject: Rotates a GameObject to a new rotation (local or world space, Euler angles or quaternion)

  Example prompt: "Rotate the Camera 45 degrees on the Y axis"

• scale_gameobject: Scales a GameObject to a new local scale

  Example prompt: "Scale the Enemy object to twice its size"

• set_transform: Sets position, rotation, and scale of a GameObject in a single operation

  Example prompt: "Set the Cube's position to (0, 5, 0), rotation to (0, 90, 0), and scale to (2, 2, 2)"

• create_material: Creates a new material with specified shader and saves it to the project

  Example prompt: "Create a red material called 'EnemyMaterial' using the URP Lit shader"

• assign_material: Assigns a material to a GameObject's Renderer component

  Example prompt: "Assign the 'EnemyMaterial' to the Enemy GameObject"

• modify_material: Modifies properties of an existing material (colors, floats, textures)

  Example prompt: "Change the color of 'EnemyMaterial' to blue and set metallic to 0.8"

• get_material_info: Gets detailed information about a material including shader and all properties

  Example prompt: "Show me all the properties of the 'PlayerMaterial'"

• batch_execute: Executes multiple tool operations in a single batch request, reducing round-trips and enabling atomic operations with optional rollback on failure

  Example prompt: "Create 10 empty GameObjects named Enemy_1 through Enemy_10 in a single batch operation"

MCP App tools

• show_unity_dashboard: Opens the Unity dashboard MCP App in VS Code (requires VS Code 1.109+)

  Example prompt: "Open the Unity dashboard app"

• get_play_mode_status: Gets Unity play mode status (isPlaying, isPaused)

  Example prompt: "Is Unity in play mode?"

• set_play_mode_status: Controls Unity play mode with actions: 'play' (start or unpause), 'pause' (toggle pause), 'stop' (exit play mode), 'step' (advance one frame)

  Example prompt: "Start Unity play mode" or "Pause the game" or "Step forward one frame"

MCP Server Resources

• unity://menu-items: Retrieves a list of all available menu items in the Unity Editor to facilitate execute_menu_item tool

  Example prompt: "Show me all available menu items related to GameObject creation"

• unity://scenes-hierarchy: Retrieves a list of all game objects in the current Unity scene hierarchy

  Example prompt: "Show me the current scenes hierarchy structure"

• unity://gameobject/{id}: Retrieves detailed information about a specific GameObject by instance ID or object path in the scene hierarchy, including all GameObject components with it's serialized properties and fields

  Example prompt: "Get me detailed information about the Player GameObject"

• unity://logs: Retrieves a list of all logs from the Unity console

  Example prompt: "Show me the recent error messages from the Unity console"

• unity://packages: Retrieves information about installed and available packages from the Unity Package Manager

  Example prompt: "List all the packages currently installed in my Unity project"

• unity://assets: Retrieves information about assets in the Unity Asset Database

  Example prompt: "Find all texture assets in my project"

• unity://tests/{testMode}: Retrieves information about tests in the Unity Test Runner

MCP Server Prompts

Prompts are pre-configured templates that provide guided workflows for common Unity tasks. They help AI assistants understand the proper sequence of operations and available tools for specific scenarios.

• unity_dashboard: Opens the Unity dashboard MCP app with contextual information about its features

  Usage: In your AI assistant, use the prompt "unity_dashboard" to get guided access to the Unity dashboard

• gameobject_handling_strategy: Provides a structured workflow for working with GameObjects, including which tools and resources to use

  Usage: In your AI assistant, use the prompt "gameobject_handling_strategy" with a GameObject ID, name, or path to get step-by-step guidance

When running the MCP (Node.js) server inside WSL2 while Unity runs on Windows 11, connecting to ws://localhost:8090/McpUnity may fail with ECONNREFUSED.

Cause: WSL2 and Windows have separate network namespaces — localhost inside WSL2 does not point to the Windows host. By default, Unity listens on localhost:8090.

Solution 1 — Enable WSL2 Mirrored mode networking (preferred)

• Windows 11: Settings → System → For developers → WSL → Enable “Mirrored mode networking”.
• Or via .wslconfig (then run wsl --shutdown and reopen WSL):

[wsl2]
networkingMode=mirrored

After enabling, localhost is shared between Windows and WSL2, so the default config (localhost:8090) works.

Solution 2 — Point the Node client to the Windows host

Set in your WSL shell before starting the MCP client:

# Use the Windows host IP detected from resolv.conf
export UNITY_HOST=$(grep -m1 nameserver /etc/resolv.conf | awk '{print $2}')

With this, Server~/src/unity/mcpUnity.ts will connect to ws://$UNITY_HOST:8090/McpUnity instead of localhost (it reads UNITY_HOST, and may also honor a Host in ProjectSettings/McpUnitySettings.json if present).

Solution 3 — Allow remote connections from Unity

Example prompt: "List all available tests in my Unity project"

• Unity: Tools → MCP Unity → Server Window → enable “Allow Remote Connections” (Unity binds to 0.0.0.0).
• Ensure Windows Firewall allows inbound TCP on your configured port (default 8090).
• From WSL2, connect to the Windows host IP (see Solution 2) or to localhost if mirrored mode is enabled.

[!NOTE] Default port is 8090. You can change it in the Unity Server Window (Tools → MCP Unity → Server Window). The value maps to McpUnitySettings and is persisted in ProjectSettings/McpUnitySettings.json.

Validate connectivity

npm i -g wscat
# After enabling mirrored networking
wscat -c ws://localhost:8090/McpUnity
# Or using the Windows host IP
wscat -c ws://$UNITY_HOST:8090/McpUnity