Skip to content

Examples and Tutorials

Jump to bottom
Ivan Murzak edited this page Mar 9, 2026 · 2 revisions

Examples and Tutorials

Practical workflows using Unity-MCP's 52 tools, 48 prompts, and 1 resource. All examples show what you can ask your AI client to do once Unity-MCP is connected.

Getting Started

Prerequisites

  1. Unity 2022.3+ with Unity-MCP plugin installed
  2. Open Window > AI Game Developer and verify the connection is active
  3. Your AI client (Claude Desktop, Cursor, VS Code Copilot, etc.) configured and connected

Understanding Tool Names

Unity-MCP tools use kebab-case names with a category prefix. For example:

  • gameobject-create -- creates a new GameObject
  • assets-find -- searches the asset database
  • scene-save -- saves the current scene

Your AI client calls these tools automatically based on your natural language requests.

Workflow 1: Setting Up a Scene

Ask your AI client:

"Create a new scene called 'Level01', then add a ground plane at the origin scaled to (20, 1, 20), a directional light angled downward, and a camera at position (0, 10, -10) looking at the center."

Behind the scenes, the AI will use:

  • scene-create to create the new scene
  • gameobject-create to create the ground plane (with primitiveType: Plane), light, and camera
  • gameobject-component-add to add a Light component and configure it
  • gameobject-modify to set transforms, names, and properties
  • scene-save to save the result

Organizing the Hierarchy

"Organize the scene hierarchy: create empty parent GameObjects named 'Environment', 'Lighting', and 'Cameras'. Move the ground under Environment, the directional light under Lighting, and the camera under Cameras."

This uses:

  • gameobject-create for the empty parent objects
  • gameobject-set-parent to reparent objects
  • gameobject-find to locate existing objects by name

Workflow 2: Creating GameObjects with Components

"Create a player character: a capsule named 'Player' at position (0, 1, 0) with a Rigidbody (no angular rotation on X and Z), a CapsuleCollider, and tag it as 'Player'."

This uses:

  • gameobject-create with primitiveType: Capsule
  • gameobject-component-add for Rigidbody and CapsuleCollider
  • gameobject-component-modify to configure Rigidbody constraints
  • gameobject-modify to set the tag

Inspecting Components

"Show me all components on the Player GameObject and their property values."

This uses:

  • gameobject-find to locate the Player
  • gameobject-component-list-all to list all components
  • gameobject-component-get to read property values of each component

Modifying Component Properties

"Set the Rigidbody mass to 2, drag to 0.5, and freeze rotation on X and Z axes."

This uses:

  • gameobject-component-modify with the specific property values in JSON format

Workflow 3: Managing Assets

Searching and Browsing

"Find all prefabs in the project that contain 'Enemy' in the name."

Uses assets-find with filter t:Prefab Enemy.

"Find all materials using the Standard shader."

Uses assets-find with filter t:Material and then assets-get-data to inspect shader references.

Creating Materials

"Create a red metallic material called 'PlayerMaterial' at Assets/Materials/ using the Universal Render Pipeline/Lit shader."

Uses:

  • assets-create-folder to ensure Assets/Materials/ exists
  • assets-material-create to create the material with the specified shader
  • assets-modify to set color and metallic properties

Working with Prefabs

"Save the Player GameObject as a prefab at Assets/Prefabs/Player.prefab."

Uses:

  • assets-create-folder to ensure Assets/Prefabs/ exists
  • assets-prefab-create to save the GameObject as a prefab

"Instantiate the Enemy prefab from Assets/Prefabs/Enemy.prefab at positions (5, 0, 0), (-5, 0, 0), and (0, 0, 5)."

Uses assets-prefab-instantiate three times with different positions.

Editing Prefabs

"Open the Player prefab for editing and add an AudioSource component, then save and close."

Uses:

  • assets-prefab-open to enter prefab editing mode
  • gameobject-component-add to add the AudioSource
  • assets-prefab-save to save changes
  • assets-prefab-close to exit prefab editing mode

Workflow 4: Writing and Managing Scripts

Creating a Script

"Create a C# MonoBehaviour script at Assets/Scripts/PlayerMovement.cs with WASD movement, jumping with Space, and a configurable speed field."

Uses script-update-or-create with the full C# source code.

Reading an Existing Script

"Show me the contents of Assets/Scripts/PlayerMovement.cs."

Uses script-read to return the file contents.

Executing Code at Runtime

"Execute a script that logs all GameObjects in the scene with their world positions."

Uses script-execute to compile and run C# code dynamically via Roslyn. The script runs in the editor context and can access the full Unity API.

Workflow 5: Taking Screenshots

"Take a screenshot from the Scene View so I can see the current layout."

Uses screenshot-scene-view. The image is returned directly to the AI client for visual inspection.

"Take a screenshot from the Main Camera at 1920x1080 resolution."

Uses screenshot-camera with the specified resolution.

"Capture the Game View to see how the UI looks."

Uses screenshot-game-view.

Screenshots are especially useful for iterative visual work -- the AI can see the result and suggest adjustments.

Workflow 6: Running Tests

"Run all EditMode tests and tell me if anything fails."

Uses tests-run to execute the test suite. Results are returned with pass/fail status and error details.

"Run only the tests in the 'PlayerMovement' category."

Uses tests-run with a filter parameter.

Workflow 7: Package Management

"List all installed packages in this project."

Uses package-list.

"Search for a 2D animation package on the Unity registry."

Uses package-search.

"Install the TextMeshPro package."

Uses package-add with the package identifier.

"Remove the package com.unity.collab-proxy."

Uses package-remove.

Workflow 8: Editor State and Selection

"What is the current editor state -- is the game playing or paused?"

Uses editor-application-get-state.

"Enter Play mode."

Uses editor-application-set-state.

"Select the Main Camera in the editor."

Uses gameobject-find to locate it, then editor-selection-set.

"What objects are currently selected in the editor?"

Uses editor-selection-get.

Workflow 9: Reflection and Advanced Operations

"Find all public methods on the EditorApplication class."

Uses reflection-method-find to search for methods by type name.

"Call AssetDatabase.Refresh() to reimport all assets."

Uses reflection-method-call for direct Unity API invocation, or simply assets-refresh.

Workflow 10: Using Prompts for Complex Tasks

Prompts provide structured guidance for multi-step tasks. Ask your AI client to use them:

"Use the setup-basic-scene prompt to create a starter scene."

"Use the setup-player-controller prompt to create a full player character with movement."

"Use the organize-project-structure prompt to set up standard folders for my project."

"Use the create-unit-tests prompt to generate tests for my PlayerMovement script."

Available Prompt Categories

  • Scene Management: setup-basic-scene, organize-scene-hierarchy, add-lighting-setup, setup-scene-camera, create-prefab-from-selection, create-environment-template
  • GameObject & Component: add-standard-components, setup-player-controller, create-ui-canvas, add-physics-interactions, create-interactive-object, setup-audio-source, create-particle-effects, setup-animator-component
  • Scripting & Code: generate-monobehaviour-template, add-event-system, create-singleton-manager, setup-coroutine-framework, create-scriptableobject-data, implement-object-pooling, add-state-machine, setup-dependency-injection
  • Asset Management: organize-project-structure, import-setup-sprites, setup-audio-manager, configure-build-settings, create-material-library, setup-asset-bundles, optimize-texture-settings, setup-addressables
  • Debugging & Testing: add-debug-visualization, setup-performance-profiling, create-test-scene, add-logging-system, create-unit-tests, setup-debug-ui, add-assertion-checks, create-automated-tests
  • Animation & Timeline: setup-animator-controller, create-simple-tweening, setup-timeline-sequence, add-animation-events, create-procedural-animation, setup-sprite-animation, add-ik-system, create-animation-blending

Workflow 11: Browsing the Scene Resource

Unity-MCP exposes 1 resource: the GameObject hierarchy from the current scene. The AI client can read gameobject://currentScene/{path} to get component data and property values for any GameObject by its hierarchy path.

"Read the resource for the Main Camera to see all its component properties."

The resource returns JSON with the full component data for the specified GameObject.

Adding Custom Tools

You can extend Unity-MCP with project-specific tools:

[McpPluginToolType]
public partial class Tool_MyCustom
{
    [McpPluginTool("my-custom-tool", Title = "My Custom Tool")]
    [Description("Does something project-specific.")]
    public string MyTool(
        [Description("Input parameter.")] string input
    )
    {
        return MainThread.Instance.Run(() =>
        {
            // Your Unity API code here
            return $"[Success] Processed: {input}";
        });
    }
}

See the Custom Tools Development guide for full details.

Tips

  • Be specific: "Create a cube named 'Obstacle' at (3, 0.5, 0) with a red material and a BoxCollider" works better than "add an obstacle."
  • Iterate visually: Use screenshot-scene-view or screenshot-game-view to let the AI see results and make adjustments.
  • Use prompts for scaffolding: Prompts give the AI structured patterns for common multi-step tasks.
  • Check the console: Ask the AI to use console-get-logs if something seems wrong.
  • Save often: Ask the AI to use scene-save after significant changes.

Clone this wiki locally