# Unity — Effective AI Requests

Unity-MCP (branded "AI Game Developer — Unity") is an MCP plugin for the Unity Editor and Runtime. It exposes Unity Editor operations — scenes, GameObjects, components, prefabs, assets, materials, C# scripts, the package manager, the profiler, screenshots, and the test runner — as AI Tools, so an MCP-compatible AI client can drive the Unity Editor through natural language. Unlike Unreal and Godot, Unity-MCP also works inside your compiled game (Runtime), enabling real-time AI debugging and player-AI interaction in-game.

_Last updated: 2026-06-17_

Unity 2022.3 LTS or newer (2022.3, 2023, Unity 6 / 6000.x). Package: com.ivanmurzak.unity.mcp.

## Tool-family map

| Family | Tools | Purpose |
| --- | --- | --- |
| Scene | 7 | Create, open, save, set-active, unload, list-opened, get hierarchy data. |
| GameObject | 6 | Create, destroy, duplicate, find, modify, set-parent objects. |
| Component | 5 | Add, get, list-all, modify, destroy components on a GameObject. |
| Asset | 9 | Find, get-data, copy, move, delete, create-folder, refresh, modify, find-built-in. |
| Prefab | 5 | Create, open, close, save, instantiate prefabs. |
| Script | 4 | Update-or-create, read, delete, execute C# scripts. |
| Editor | 6 | Selection get/set, play-mode get/set, Tool/List, Tool/Set-Enabled-State. |
| Console | 2 | Read recent log messages; clear the console. |
| Profiler | 12 | Start/stop/capture profiling; memory/rendering/script stats; save/load .raw. |
| Screenshot | 4 | Camera, game view, scene view, isolated-GameObject renders. |
| Reflection | 3 | Find/call C# methods via reflection; get a type’s JSON schema. |
| Extensions | 114 | Animation, Particles, ProBuilder, Cinemachine, Splines, Terrain, Input System, Tilemap, Navigation, Timeline — each from a separate unity-ai-* package. |

Unity exposes 190 tools across 27 families: 76 are core (ship with com.ivanmurzak.unity.mcp); 114 come from 10 optional unity-ai-* extension packages. A family’s tools are only available when its package is installed.

## Example prompts

1. Create a new scene with a directional light and a rotating cube, then enter Play mode.
2. Create an empty GameObject called `SpawnPoint` at world origin, then add a Rigidbody to it and set its mass to 5.
3. Make a prefab from the `FlyingDrone` GameObject, then drop 10 instances of it along the road.
4. Add a `HealthBar.cs` script with a public float `health` property, attach it to the Player, then compile and fix any console errors.
5. Take a 1920×1080 screenshot from the cinematic camera so I can see the framing.
6. Start profiling CPU and memory, enter Play mode for a few seconds, then tell me which scripts are taking the most CPU time.
7. Create a Cinemachine camera that follows the Player. (Requires the AI Cinemachine extension.)

## Your first request

1. Open Window → AI Game Developer, choose Cloud, click Authorize, and wait for the status pill to read Ready (green).
2. Ask your client: "Ping the Unity MCP server and confirm we are connected."
3. Ask: "In the active scene, create a cube named `Hero` at the origin, then take a screenshot."
4. Confirm the cube appears in the Editor and read back the screenshot.
5. Build up from there — add a component, write a script, then "compile and fix any errors".

## Discover what the agent can do

1. Ping the Unity MCP server and confirm we are connected. (ping)
2. What tools can you call right now? (unity-tool-list / "Tool / List")
3. Group your tools by family and give me a one-line purpose for each.
4. Which extension families do I have installed — Cinemachine, Terrain, Timeline, ProBuilder, …?
5. List every GameObject in the active scene with their components. (scene-get-data)
6. Pick one family and ask for a tiny concrete action plus a screenshot.

## Common pitfalls

- Runtime vs Editor scope. Unity-MCP uniquely works inside a compiled build, but most catalog tools are Editor-scoped — be explicit when you want runtime behavior.
- Extensions gate families. If the agent reports no Terrain / Timeline / Cinemachine tool, the matching unity-ai-* package is not installed. Install it (e.g. openupm add com.ivanmurzak.unity.mcp.cinemachine) and reopen the project.
- Prefer Auto-generate skills in the editor panel — Unity-MCP can auto-generate parameterized "skills" tailored to your OS, Unity version, and installed packages for the smoothest agent setup.
- Per-tool enable/disable is enforced at the execution boundary (tool-set-enabled-state) — useful for sandboxing, e.g. disabling script execution during review.

---

Source (HTML): https://ai-game.dev/docs/best-practices/unity