Unity MCP: How to Connect an AI Assistant to Unity on Windows and Mac

By Shah Rukh, software developer · October 2, 2026 · 7 min read

Unity MCP (the project now calls itself AI Game Developer) is an open-source plugin that lets an AI assistant such as Claude Code, Cursor or GitHub Copilot work directly inside the Unity game engine. This guide covers what you need, how to install it on Windows and Mac, how to connect your AI assistant, and the precautions to take before you let it touch a project.

Read this first. Unity MCP does not include an AI model. It is only the bridge. You still need the Unity Editor and a separate AI assistant, and that assistant may need its own paid plan or API credit. Once connected, the AI can create, change and delete assets and scripts and run C# code in your project, so back up your project first.

What Unity MCP is

MCP stands for Model Context Protocol. It is a standard way for an AI assistant to use outside tools. The README calls it “USB Type-C for AI”.

Unity MCP has three parts that talk to each other:

The project says the plugin ships with more than 70 built-in tools in four groups: project and assets, scene and hierarchy, scripting and editor, and profiling. Examples from the README are gameobject-create, scene-save, script-update-or-create, tests-run and screenshot-game-view. It also says the plugin can run inside a finished game, not only in the editor, but no tools exist there by default. You have to write your own.

The code is published under the Apache 2.0 licence. It is an independent project by Ivan Murzak. It is not made by Unity or by any AI company.

What you need

• The Unity Editor. The plugin’s package file lists Unity 2022.3 as the minimum version.
• A Unity project in a folder path with no spaces. The README marks this as a requirement: C:/MyProjects/MyProject works, C:/My Projects/MyProject does not.
• One AI agent. The README recommends Claude Code and also lists Claude Desktop, GitHub Copilot in VS Code, Antigravity, Cursor and Windsurf. You only need one. The project says the agent must support Skills or dynamic MCP tool updates.
• Node.js, only if you use the command-line method. The CLI needs version ^20.19.0 or >=22.12.0.
• An ai-game.dev account, only if you use the project’s cloud connection. The CLI signs you in through your browser.

Costs: the plugin and CLI are free and open source. The repository does not list any prices for the ai-game.dev cloud service, so check that site yourself. Your AI agent and Unity have their own pricing and licence terms, which this project does not control.

Precautions before you install

1. Back up the project. Tools such as assets-delete, script-delete and gameobject-destroy remove things. Put the project in Git or make a copy, and try the plugin on a test project first.
2. The AI can run code. script-execute compiles and runs C# on the spot, and reflection-method-call can call any C# method, even private ones. Read each permission prompt in your AI agent before you approve it.
3. Your project data leaves your computer. Scene contents, scripts, logs and screenshots that the AI reads are sent to the company behind your AI agent. Don’t use it on client or company work without permission.
4. Know which connection you use. The plugin has two connection modes, Cloud and Custom. Cloud goes through the project’s ai-game.dev service. Custom uses a server you run yourself, for example on your own computer.
5. Protect the saved credentials. unity-mcp-cli login saves a credential in ~/.ai-game-dev/credentials.json, and project keys go in ~/.ai-game-dev/project-keys.json. Connection settings and tokens are in UserSettings/AI-Game-Developer-Config.json inside the project. Don’t share or commit these files.
6. Turn on a token if you host the server. The standalone server’s authorization setting defaults to none. If the server can be reached from other machines, set MCP_AUTHORIZATION to token and choose a long random MCP_PLUGIN_TOKEN.
7. Only use the real repository: github.com/IvanMurzak/Unity-MCP. On Windows the CLI may install Unity Hub silently if it is missing, which can ask for administrator rights.

How to install Unity MCP with the installer (Windows and Mac)

This method is the same on both systems and needs no terminal.

1. Download AI-Game-Dev-Installer.unitypackage from the project’s releases page.
2. Open your project in the Unity Editor.
3. Double-click the downloaded file, or in Unity choose Assets, then Import Package, then Custom Package, and pick the file.
4. Wait for Unity to finish importing and compiling.

How to install Unity MCP with the CLI on Windows and Mac

The README recommends this method. The commands are the same on Windows (PowerShell) and Mac (Terminal). Install Node.js first, then change ./MyUnityProject to your own project path.

1. Install the CLI:

   npm install -g unity-mcp-cli

2. Add the plugin to your project. This edits Packages/manifest.json and adds the OpenUPM package registry:

   unity-mcp-cli install-plugin ./MyUnityProject

3. Sign in to ai-game.dev. It opens your browser and shows a short code to approve:

   unity-mcp-cli login

4. Open the project in Unity:

   unity-mcp-cli open ./MyUnityProject

5. Wait until Unity and the server are ready:

   unity-mcp-cli wait-for-ready ./MyUnityProject

If you don’t have Unity or a project yet, the CLI has two optional commands: unity-mcp-cli install-unity and unity-mcp-cli create-project ./MyUnityProject.

Mac note: the open command tries to dismiss Unity’s “compile errors at launch” dialog for you. On macOS this needs Accessibility permission for your terminal, under System Settings, Privacy & Security, Accessibility. To skip the feature, add --no-auto-dismiss-launch-errors.

Connect your AI agent

1. In Unity, open Window, then AI Game Developer.
2. Click Auto-generate skills (the recommended option), or click Configure to set up MCP for your agent.
3. If your agent is not in the list, copy the raw JSON shown in the window into your agent’s MCP settings.

You can do the same from the command line. This example is for Claude Code:

unity-mcp-cli setup-skills claude-code ./MyUnityProject
unity-mcp-cli setup-mcp claude-code ./MyUnityProject

Run unity-mcp-cli setup-mcp --list to see all 14 supported agent names. By default setup-mcp writes a config that points to the ai-game.dev cloud. To have your agent start the local server instead, add --transport stdio.

First use

Keep Unity open, start your AI agent in the project folder and type a small request. The README suggests these:

• Explain my scene hierarchy
• Create 3 spheres on top of each other
• Create metallic golden material and attach it to a new sphere gameObject

In VS Code with Copilot, make sure Agent mode is on. Results depend heavily on the model your agent uses, so check what it built.

Useful settings and features

The standalone server uses port 8080 by default and shuts down after 600 seconds with no connections. When the CLI and plugin run a local server, they pick a fixed port for each project in the range 20000–29999, based on the project path.

How to uninstall Unity MCP

1. In Unity, open Window, then Package Manager, select AI Game Developer — MCP and click Remove.
2. Close Unity and delete the Assets/Plugins/NuGet folder and its Assets/Plugins/NuGet.meta file.

From the command line, unity-mcp-cli remove-plugin ./MyUnityProject removes the plugin from the manifest and leaves the package registry entry in place. The project does not document a separate update command. The plugin shows a popup in the editor when a newer version is available.

Common problems

For anything else, report the problem on GitHub.

This guide is based on the project’s repository as it was on October 2, 2026. The project changes often, so if a step looks different, follow the README on GitHub. ToolsCloset is not connected to the project, to Unity Technologies or to any AI provider. Unity is a trademark of Unity Technologies.

More AI tips

Related tools