Skip to content
IvanMurzakPublic

About

AI Skills, MCP Tools, and CLI for Unity Engine. Full AI develop and test loop. Use cli for quick setup. Efficient token usage, advanced tools. Any C# method may be turned into a tool by a single line. Works with Claude Code, Gemini, Copilot, Cursor and any other absolutely for free.

Topics

Resources

Stars

4.6k stars

Watchers

31 watching

Forks

Repository files navigation

AI Game Developer for Unity: Skills, MCP tools and a CLI that connect AI agents to the Unity Editor and to your running game

OpenUPM version OpenUPM downloads per month unity-mcp-cli on npm Unity 2022.3 or newer
Release workflow status Discord License Stand with Ukraine

Claude   Codex   Cursor   GitHub Copilot   Gemini   Antigravity   VS Code   Rider   Visual Studio   Open Code   Cline   Kilo Code

中文 | 日本語 | Español | فارسی | हिन्दी | العربية

AI Game Developer (Unity-MCP) connects your AI agent to Unity. Claude Code, Codex, Cursor, GitHub Copilot, Gemini or any other MCP client can read and change scenes, prefabs, assets and C# code, run tests and take screenshots in the Unity Editor, and call tools you write inside your compiled game. It ships as a free Unity package (com.ivanmurzak.unity.mcp), a command-line tool (unity-mcp-cli) and optional extensions.

Status: latest release and changelog. The plugin and unity-mcp-cli share one version. Tested and supported on Windows, macOS and Linux. Requires Unity 2022.3 or newer; CI runs EditMode, PlayMode and standalone-build tests on Unity 2022.3, 6000.0, 6000.3 and 6000.6.

How it works

An AI agent or unity-mcp-cli talks MCP to a server, ai-game.dev Cloud by default or a local gamedev-mcp-server, which calls the tools of the Unity Editor plugin and of your running game

The plugin registers its tools with an MCP server; your agent calls them through that server. Instead of MCP tools, the agent can also use generated Skills. You choose where the server runs:

Local (Custom mode, no account) Cloud (default setting)
Server GameDev-MCP-Server started by the plugin on 127.0.0.1, or one you host https://ai-game.dev/mcp
Account Not needed Sign in to ai-game.dev
Your project data Stays on your machine Tool calls pass through a stateless relay that does not inspect or persist their contents; it records MCP event metadata, used within a rolling 90-day window (Privacy Policy)
Cost Free Free

Why Cloud is the default: it needs no open ports and avoids port conflicts with other programs, and it is free. Local is an equal option for offline or air-gapped work. Details: Security and privacy.

Features

✅ Covers the Editor — the agent can do virtually anything you can do in the Unity Editor
✅ Compact and efficient — tools built for agents: fewer calls and fewer tokens, so the agent works faster and cheaper (measured in the Unity Editor)
✅ RQL — read and change scenes, objects, assets and settings with one query language
✅ C# and tests — compile and run C# with Roslyn; run EditMode and PlayMode tests
✅ Skills or MCP — generate Skills in one click, or connect as an MCP client
✅ Any agent — Claude Code, Codex, Cursor, Copilot, Gemini and other MCP clients
✅ Runtime — the same tools inside your built game: NPC logic, live debugging
✅ Your own tools — any C# method becomes a tool with one [AiTool] attribute
✅ CLI — install, open, query, compile and test from the terminal or CI
✅ Extensions — optional tool packs, from Animation to Timeline

Quick start

Requires Unity 2022.3 or newer.

1. Install the plugin (recommended: the Installer, nothing else to install):

DOWNLOAD INSTALLER

Open the downloaded .unitypackage with your project open (double-click it, or Assets ▸ Import Package ▸ Custom Package).

Other ways to install: OpenUPM / Package Manager, or the CLI for scripting and CI
  • OpenUPM — openupm add com.ivanmurzak.unity.mcp, or without any CLI: add a scoped registry in Edit ▸ Project Settings ▸ Package Manager (URL https://package.openupm.com, scopes com.ivanmurzak and extensions.unity), then Window ▸ Package Manager ▸ + ▸ Add package by name → com.ivanmurzak.unity.mcp.

  • unity-mcp-cli (Node.js 22.14+) — for scripts and CI, no Editor needed:

    npm install -g unity-mcp-cli
    unity-mcp-cli install-plugin ./MyUnityProject   # add the plugin to Packages/manifest.json
    unity-mcp-cli open ./MyUnityProject             # open the project in Unity

    Terminal session: install unity-mcp-cli, add the plugin, sign in, configure Claude Code and open the project

2. Connect your agent — pick one; both are fully supported:

Local (no account) Cloud (default setting)
In Window ▸ AI Game Dev connection Custom connection Cloud, then Authorize (browser sign-in)
Agent config Configure for your agent Configure for your agent
Same from the CLI unity-mcp-cli setup-mcp claude-code ./MyUnityProject --transport stdio unity-mcp-cli login, then unity-mcp-cli setup-mcp claude-code ./MyUnityProject

Auto-generate Skills in the same window is the alternative to MCP. Other agents: client setup.

3. Local only: choose who may call your tools. The local server starts with auth none: it listens only on 127.0.0.1 and rejects foreign browser origins, but any program on your machine can reach it. If other people or untrusted programs use the machine, switch to token in one step: Window ▸ AI Game Dev → Authorization Token → token. The server restarts with a generated secret; press Configure again so your agent sends it.

AI Game Developer window

Ask your agent "Create 3 cubes in a circle with radius 2" and watch it happen. Full steps, manual MCP configuration and uninstall: Installation guide.

ai-game-dropship-flying.mp4

Usage

Talk to your agent. Describe the result you want; the more precise, the better.

Explain my scene hierarchy
Create metallic golden material and attach it to a new sphere
Find every enemy prefab without a Rigidbody and add one

What your agent can do (tools shown by default):

Capability Tool Example prompt
Scenes and GameObjects rql-query, rql-mutate "List every disabled GameObject in the open scene"
Assets and prefabs rql-query, rql-mutate "Create a red material and assign it to all cubes"
Console and Editor state rql-query "What errors are in the console?"
C# in the Editor script-execute "Run C# that places 100 trees at random points on the terrain"
Tests tests-run "Run the EditMode tests and fix what fails"
Screenshots screenshot-isolated "Show me the Player model from the front"
Packages and Asset Store package-*, assetstore-* "Install Cinemachine"
Tool list unity-tool-list "Which tools can you use here?"

You do not learn RQL: the agent writes it and asks rql-schema for every source, type and call it needs. Measured in the Unity Editor: the same tasks took about 5× fewer prompt tokens and fewer tool calls than one-tool-per-action tools, at the same success rate (benchmark). On a sandbox game world, with RQL an agent needs about 2–3 tool calls and 7–8k tokens per task at 100% success, versus 30–37 calls and 125–170k tokens at 67–91% success with plain reflection tools (results). More tools are installed but hidden until you show them. Full list: Default MCP tools or ai-game.dev/docs/tools.

From the terminal (starts a headless editor when none is running):

unity-mcp-cli rql 'objects | where name starts-with "Tree" | count'
unity-mcp-cli compile ./MyGame
unity-mcp-cli test ./MyGame --mode PlayMode

Your own tool. A class with [AiToolType] and a method with [AiTool] is all it takes:

[AiToolType]
public class Tool_Score
{
    [AiTool("score-reset", Title = "Reset the score")]
    [Description("Sets the player's score to zero.")]
    public string Reset()
    {
        return MainThread.Instance.Run(() =>
        {
            ScoreManager.Instance.Score = 0;
            return "[Success] Score reset.";
        });
    }
}

Prompts, runtime (in-game) tools and a full example: Custom tools and runtime.

Client setup

The Configure button in the AI Game Developer window, or unity-mcp-cli setup-mcp <agent> ./MyUnityProject, writes these files for you (Cloud by default, local with --transport stdio). By hand, for a local server: set the plugin to Custom, take <port> from the window, and use the binary for your platform from <project>/Library/mcp-server/<rid>/ (win-x64/gamedev-mcp-server.exe, osx-arm64/gamedev-mcp-server, linux-x64/gamedev-mcp-server, …).

Claude Code — .mcp.json in the project root
{
  "mcpServers": {
    "ai-game-developer": {
      "command": "<project>/Library/mcp-server/win-x64/gamedev-mcp-server.exe",
      "args": ["port=<port>", "client-transport=stdio"]
    }
  }
}
Cursor — .cursor/mcp.json
{
  "mcpServers": {
    "ai-game-developer": {
      "type": "stdio",
      "command": "<project>/Library/mcp-server/win-x64/gamedev-mcp-server.exe",
      "args": ["port=<port>", "client-transport=stdio"]
    }
  }
}
Codex — .codex/config.toml
[mcp_servers.ai-game-developer]
enabled = true
command = "<project>/Library/mcp-server/win-x64/gamedev-mcp-server.exe"
args = ["port=<port>", "client-transport=stdio"]
tool_timeout_sec = 300

Other agents and manual setup: Installation guide.

Security and privacy

Most private setup: connection Custom (local server on 127.0.0.1, no account, project data stays on your machine) with Authorization Token set to token in Window ▸ AI Game Dev, then Configure again so your agent sends the secret.

✅ The plugin opens no port — it connects out to the MCP server.
✅ Local server on loopback — gamedev-mcp-server binds to 127.0.0.1 unless you set MCP_BIND for hosting.
✅ Origin checks — browser requests with a non-allowed Origin are rejected (403) in every auth mode.
✅ Auth modes — none (local default), token (one shared secret the agent and the plugin must both send), oauth (ai-game.dev account).
✅ Cloud relay — a stateless relay: it routes tool calls between your agent and the Editor without inspecting or persisting their contents, and does not collect conversations, source code, project files, assets or scene data. It records MCP event metadata (event type, timing, status, session identifiers, the tool, prompt or resource name, error details), used within a rolling 90-day window (Privacy Policy).
⚠️ Not protected — in none mode any process on your machine that reaches the port can call tools, and tools run with Editor rights (script-execute runs C#). Use token mode on shared machines.

Server options and Docker: MCP server and connection.

Extensions

Extensions are optional UPM packages that add tools for specific Unity features.

unity-mcp-cli install-extension com.ivanmurzak.unity.mcp.cinemachine ./MyUnityProject
Extension Adds Requires
Animation AnimationClips and AnimatorControllers
Cinemachine Virtual cameras, targets and the camera pipeline com.unity.cinemachine 3.1.6+
InputSystem Input action assets, maps, actions and bindings com.unity.inputsystem 1.8.2+
Navigation NavMesh surfaces, baking, agents and links com.unity.ai.navigation 1.1.7+
ParticleSystem ParticleSystem emission, shape, curves and gradients
ProBuilder Editable meshes: shapes, extrude, bevel, materials com.unity.probuilder 5.2.4+
Splines Spline containers, knots and tangents com.unity.splines 2.8.4+
Terrain Terrains: heightmaps, sculpting and sampling
Tilemap Grids and tilemaps: paint, fill and read tiles com.unity.2d.tilemap.extras 3.1.3+
Timeline Timeline assets, tracks, clips and markers com.unity.timeline 1.8.12+

Required Unity packages install with the extension. You can also install extensions from the Extensions section of the AI Game Developer window.

Documentation

Page What is in it
Installation guide Install options, connecting an agent, manual MCP config, team settings, uninstall
Benchmark Unity Editor and sandbox measurements: tokens, tool calls and success with RQL tools
Default MCP tools Every built-in tool, RQL sources, tools removed in 1.0.0 and their RQL equivalents
Custom tools and runtime Write tools and prompts; use MCP inside your game
MCP server and connection Cloud and Custom modes, plugin environment variables, local server
Docker deployment Run the MCP server in a container
Disable in CI Keep the plugin out of ordinary CI test runs
CLI reference Every unity-mcp-cli command and option
Wiki Tutorials, guides and FAQ
Development guide Repository layout, code style, tests and CI for contributors

Related: GameDev-MCP-Server (the shared MCP server) · ai-game.dev · Discord

Contributing

Ideas, bug reports and pull requests are welcome. Read the Development guide, fork the repository, open ./Unity-MCP-Plugin in Unity, and send a pull request to main. If the project helps you, please give it a star.

License

Free for game development, commercial games included. The plugin is Apache-2.0. It uses RQL and Code-Exec, licensed under PolyForm Shield 1.0.0: that license restricts only companies that build competing AI tools for game development. Game developers can use everything freely.

About

AI Skills, MCP Tools, and CLI for Unity Engine. Full AI develop and test loop. Use cli for quick setup. Efficient token usage, advanced tools. Any C# method may be turned into a tool by a single line. Works with Claude Code, Gemini, Copilot, Cursor and any other absolutely for free.

Topics

Resources

Stars

4.6k stars

Watchers

31 watching

Forks

Releases

Sponsor this project

Used by

Contributors

Languages