Docs · Best Practices · Unity
Effective AI requests in Unity
The flagship catalog — 72 capabilities (21 MCP tools plus RQL), and 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 gives an MCP-compatible AI client a small set of MCP tools — RQL query / mutate / schema, C# scripts, screenshots, the test runner, the package manager — plus RQL, one query language that reads and changes scenes, GameObjects, components, prefabs, assets, materials, the console and the profiler. Each optional unity-ai-* extension teaches RQL a new area. 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 | Capabilities | Purpose |
|---|---|---|
| Query & edit (RQL) | 3 | The three tools behind everything marked RQL. |
| Scenes & objects | 5 | GameObjects, components, hierarchy, scenes. |
| Assets & prefabs | 4 | Find, organise, materials, shaders, prefabs. |
| Scripts & C# | 4 | Write, read and run C# code. |
| Editor, console & profiler | 3 | Play mode, selection, logs, performance. |
| Tests | 2 | Find, run and read Unity tests. |
| Screenshots | 4 | Let the AI see the game, a view or one object. |
| Packages | 4 | Search, add and remove UPM packages. |
| Tools & skills | 5 | Switch tools on or off, write new skills. |
| Animation | 3 | Clips, curves, animator state machines — needs the AI Animation extension. |
| Particles | 2 | All 24 ParticleSystem modules · playback — needs the AI ParticleSystem extension. |
| ProBuilder | 4 | Model and edit meshes in the editor — needs the AI ProBuilder extension. |
| Cinemachine | 4 | Virtual cameras · targets · lens · blends — needs the AI Cinemachine extension. |
| Splines | 3 | Containers · knots · tangents · evaluate — needs the AI Splines extension. |
| Terrain | 4 | Sculpt · paint · scatter trees — needs the AI Terrain extension. |
| Input System | 4 | Action maps · bindings · schemes — needs the AI InputSystem extension. |
| Tilemap | 5 | 2D grids · paint · tile assets — needs the AI Tilemap extension. |
| Navigation | 4 | NavMesh · bake · agents · links — needs the AI Navigation extension. |
| Timeline | 5 | Cutscenes · tracks · clips · binding — needs the AI Timeline extension. |
Unity has 72 capabilities in 19 areas: 21 are MCP tools; the other 51 are done through RQL (rql-query / rql-mutate). 10 areas come from optional unity-ai-* extension packages, which add no MCP tools — each contributes an RQL module, so its area is only available when the 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.Show me the Player model from the front and from above so I can check it.Start the profiler, enter Play mode for a few seconds, then tell me how much memory the game uses and what the frame time is.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 of it."
- 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")
- What can you query with RQL in this project? (rql-schema lists the sources, including the ones extensions add)
- Which extensions do I have installed — Cinemachine, Terrain, Timeline, ProBuilder, …?
- List every GameObject in the active scene with its components. (rql-query: objects | select $path name components)
- Pick one area 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 capabilities are Editor-scoped — be explicit when you want runtime behavior.
- Extensions gate areas. If the agent cannot work with Terrain / Timeline / Cinemachine, the matching unity-ai-* package is not installed: its RQL source is missing from rql-schema. Install it (e.g. openupm add com.ivanmurzak.unity.mcp.cinemachine) and let Unity recompile.
- Some tools ship switched off (script and package tools, most screenshots). If the agent says a tool is disabled, enable it in the AI Game Developer window or ask it to use tool-set-enabled-state.
- 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.