# Unity — Effective AI Requests

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.

_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 | 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

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. Show me the Player model from the front and from above so I can check it.
6. 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.
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 of it."
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. What can you query with RQL in this project? (rql-schema lists the sources, including the ones extensions add)
4. Which extensions do I have installed — Cinemachine, Terrain, Timeline, ProBuilder, …?
5. List every GameObject in the active scene with its components. (rql-query: objects | select $path name components)
6. 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.

---

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