unity-mcp

中文 | 日本語 | Español

Unity MCP is an AI-powered game development assistant for Editor & Runtime. Connect Claude, Cursor, & Windsurf to Unity via MCP. Automate workflows, generate code, and enable AI within your games.

Unlike other tools, this plugin works inside your compiled game, allowing for real-time AI debugging and player-AI interaction.

💬 Join our Discord Server - Ask questions, showcase your work, and connect with other developers!

• ✔️ AI agents - Use the best agents from Anthropic, OpenAI, Microsoft, or any other provider with no vendor lock-in
• ✔️ Tools - A wide range of default MCP Tools for operating in Unity Editor
• ✔️ Skills - Generate skills for AI based on operating system, Unity version, plugins in the project
• ✔️ Code and Tests - Develop game mechanics and test them with AI agents
• ✔️ Runtime (in-game) - Use LLMs directly inside your compiled game for dynamic NPC behavior or debugging
• ✔️ Debug support - Let AI debug and fix the problems in a project
• ✔️ Natural conversation - Chat with AI like you would with a human
• ✔️ Flexible deployment - Works locally (stdio) and remotely (http) via configuration
• ✔️ Extensible - Create custom Tools in your project code

OR use cli

# 1. Install unity-mcp-cli
npm install -g unity-mcp-cli

# 2. Install "AI Game Developer" in Unity project
unity-mcp-cli install-plugin ./MyUnityProject

# 3. Sign in to ai-game.dev (opens your browser — OAuth device flow)
unity-mcp-cli login

# 4. Open Unity project (auto-connects and generates skills)
unity-mcp-cli open ./MyUnityProject

Quick Start

Get up and running in three steps:

1. Install plugin — download the .unitypackage installer or run openupm add com.ivanmurzak.unity.mcp

   Alternative: npx unity-mcp-cli install-plugin ./MyUnityProject — see CLI documentation

2. Pick an AI agent — Claude Code, Claude Desktop, GitHub Copilot, Cursor, or any other
3. Setup AI agent — open Window/AI Game Dev in Unity and click Auto-generate skills (recommended) or Configure MCP

   Alternative: npx unity-mcp-cli setup-skills claude-code ./MyUnityProject — see CLI documentation

That's it. Ask your AI "Create 3 cubes in a circle with radius 2" and watch it happen. ✨

Skills and Tools Reference

Since 1.0.0 the plugin exposes a small set of tools, and most Editor work goes through RQL, a query language over the Editor's data: rql-query reads, rql-mutate changes, and rql-schema describes the sources, types and calls (start there when unsure). The one-tool-per-action tools of earlier versions (gameobject-create, scene-save, console-get-logs and others) were replaced by RQL in #1017. See docs/default-mcp-tools.md for the full reference.

🧰 Browse the full MCP tools registry online: ai-game.dev/docs/tools

Shown to the AI agent by default: rql-query, rql-mutate, rql-schema, screenshot-isolated, script-execute, tests-run, unity-tool-list. The other tools are installed but hidden from the agent's tool list (a hidden tool still runs when called by name). Show them with tool-set-visibility, in the AI Game Developer window, or with unity-mcp-cli configure <path> --enable-tools <ids>.

RQL (scenes, GameObjects, components, assets, console, editor)

• rql-query - Read Editor data with an RQL query, e.g. roots | recurse children | select name active
• rql-mutate - Change Editor data or call Editor operations, e.g. editor | call CreateGameObject({name: "Ground", primitive: "Plane"})
• rql-schema - Describe the sources, types, members and calls RQL can use, and print the topic guides
• Sources: scenes, roots, objects (every GameObject in the loaded scenes), selection, prefab (the prefab open in prefab mode), editor (create GameObjects, materials, folders and scenes; open and save scenes and prefabs; copy, move and delete assets; execute menu items; …), settings, console (captured Editor log entries), shaders, componentTypes, tests, testResults, profiler, lighting; assets by path with unity.asset("Assets/…")

Screenshots

• screenshot-isolated - Render a GameObject in isolation from a chosen angle (optional composite 2x2 view)
• screenshot-scene-view - Captures a screenshot from the Unity Editor Scene View (hidden by default)
• screenshot-game-view - Captures a screenshot from the Unity Editor Game View (hidden by default)
• screenshot-camera - Captures a screenshot from a camera and returns it as an image (hidden by default)
• All four take an optional savePath, for when the user wants the picture as a file: the PNG is also written inside the project (never over an existing file) and the result says Saved to <absolute path>; under Assets/ it is imported as a Unity asset

Scripting, tests and packages

• script-execute - Compiles and executes C# code dynamically using Roslyn
• script-read - Reads the content of a script file (hidden by default)
• script-update-or-create - Updates or creates script file with the provided C# code (hidden by default)
• script-delete - Delete the script file(s) (hidden by default)
• tests-run - Execute Unity tests (EditMode/PlayMode): any RQL selection over the tests source as one run, results filtered with RQL
• package-list, package-search, package-add, package-remove - Unity Package Manager packages (hidden by default)

Tool management

• unity-tool-list - List every tool and whether the agent sees it
• tool-set-visibility - Show or hide tools in the agent's tool list (hidden by default)