Docs · Best Practices · Unity
Effective AI requests in Unity
The flagship catalog — 190 tools across 27 families, plus a Runtime mode no other engine has.
What it is
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.
Unity 2022.3 LTS or newer (2022.3, 2023, Unity 6 / 6000.x). Package: com.ivanmurzak.unity.mcp.
Tool-family map
You never call tool ids by hand — but knowing the families helps you frame requests and ask the agent "what can you do with X?". The full searchable catalog lives on the Unity tools page.
| 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
Copy-pasteable first requests. Start with one, verify in the editor, then build up.
Create a new scene with a directional light and a rotating cube, then enter Play mode.Create an empty GameObject called `SpawnPoint` at world origin, then add a Rigidbody to it and set its mass to 5.Make a prefab from the `FlyingDrone` GameObject, then drop 10 instances of it along the road.Add a `HealthBar.cs` script with a public float `health` property, attach it to the Player, then compile and fix any console errors.Take a 1920×1080 screenshot from the cinematic camera so I can see the framing.Start profiling CPU and memory, enter Play mode for a few seconds, then tell me which scripts are taking the most CPU time.Create a Cinemachine camera that follows the Player. (Requires the AI Cinemachine extension.)
Your first request
A tiny, verifiable loop to confirm everything works.
- Open Window → AI Game Developer, choose Cloud, click Authorize, and wait for the status pill to read Ready (green).
- Ask your client: "Ping the Unity MCP server and confirm we are connected."
- Ask: "In the active scene, create a cube named `Hero` at the origin, then take a screenshot."
- Confirm the cube appears in the Editor and read back the screenshot.
- Build up from there — add a component, write a script, then "compile and fix any errors".
Discover what the agent can do
Discovery is conversational — ask the agent these in order to map its capabilities.
- Ping the Unity MCP server and confirm we are connected. (ping)
- What tools can you call right now? (unity-tool-list / "Tool / List")
- Group your tools by family and give me a one-line purpose for each.
- Which extension families do I have installed — Cinemachine, Terrain, Timeline, ProBuilder, …?
- List every GameObject in the active scene with their components. (scene-get-data)
- 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.