How to Connect Claude Code to Unity With Unity MCP

Unity added an official Model Context Protocol (MCP) server to its CLI in June 2026, which means Claude Code can now inspect and drive a live Unity Editor session the same way it reads and edits files in a repo — through plain-language prompts instead of manual Inspector clicks. If you've already set up MCP servers for other tools, the pattern here is identical: one CLI command starts a server, one command registers Claude Code as a client, and then you're prompting against a real running application instead of a mocked API.

This guide covers the exact commands: installing/checking the Unity CLI, starting the MCP server with unity mcp, wiring up Claude Code with unity mcp configure claude-code, verifying the connection, and the first prompts worth running before you trust it with real Editor changes.

Quick reference

What Unity MCP actually is

MCP is the open standard that lets an AI client — Claude Code, Cursor, Claude Desktop — talk to external systems through a common protocol instead of a bespoke integration per tool. Unity's MCP server exposes the currently open Unity Editor as an MCP server: scene name, GameObject hierarchy, and component data become things a connected client can read and, with permission, modify.

That's a meaningfully different shape from most MCP servers, which wrap a remote API (a database, a SaaS product, a search index). Unity MCP wraps a local desktop application that has to already be running — the server doesn't simulate a Unity project, it talks to your actual open Editor instance. If Unity isn't open, there's nothing for the MCP server to inspect.

Unity ships this server directly through its CLI rather than as a separate community package, and documents unity mcp configure <client> with explicit support for Claude, Claude Code, Cursor, and VS Code.

Step 1: Confirm the Unity CLI is installed

When you create a new Unity project, recent project templates include a "Use Unity CLI" option. If you left it checked, unity should already be on your PATH:

unity --version

If that returns a version number, you're set. If your terminal says command not found, the Unity CLI isn't installed or enabled for that machine yet — that's the case if "Use Unity CLI" was left unchecked during project creation, and you'll need to install it via Unity Hub before continuing.

Once unity --version works, check the MCP subcommands specifically:

unity mcp --help

You should see configure listed as a subcommand, along with usage examples like:

Commands:
  configure [options] [client]  Write MCP server config for an AI agent client

Examples:
  unity mcp                                   Start the MCP stdio server
  unity mcp --project-path /path/to/MyProject Start server for a specific project
  unity mcp configure claude                  Configure Claude Desktop
  unity mcp configure --list                  Show all supported clients

Step 2: Start the MCP server

From inside your Unity project directory, with the project open in the Editor:

unity mcp

This starts a stdio MCP server and blocks, waiting for a client to connect:

unity mcp: MCP server started (stdio). Waiting for a client to connect.
  Connect via Claude Desktop, Cursor, VS Code, or the MCP Inspector.
  Press Ctrl-C to stop.

You generally won't run this manually in day-to-day use — Claude Code will launch unity mcp itself once it's configured as a client, the same way any stdio MCP server gets spawned on demand. Running it by hand once is a useful sanity check that the CLI and your Editor version are compatible before you wire up a client.

Step 3: Configure Claude Code as a client

Stop the manual server (Ctrl-C) and run the configure command from your project folder:

unity mcp configure claude-code

Under the hood, this runs Claude Code's own MCP registration command for you:

Running: claude mcp add --scope user --transport stdio unity-editor-mcp unity mcp
Added stdio MCP server unity-editor-mcp with command: unity mcp to user config
File modified: /path/to/.claude.json

That --scope user matters: the server is registered once per machine, not per project. If you run unity mcp configure claude-code again from a different project folder, you'll see:

MCP server unity-editor-mcp already exists in user config
Error: claude exited with status 1.

That's not a failure — it means the configuration already succeeded on an earlier run. Claude Code will launch unity mcp from wherever you start claude, and Unity MCP auto-discovers whichever Editor instance currently has that project open, so there's no need to reconfigure per project.

Step 4: Verify the connection

Before touching real work, confirm Claude Code actually sees the server:

claude mcp list

You should see unity-editor-mcp in the output. If it's missing, re-run unity mcp configure claude-code and check the File modified path it reports actually matches your Claude Code config location.

Step 5: Use it inside Claude Code

Keep your Unity project open in the Editor, then from the project folder:

cd ~/path/to/MyGame
claude

Claude Code launches its interactive session. Don't hand it a build task first — start with something read-only and easy to verify:

Use the Unity MCP tools to inspect my currently open Unity project.

Tell me:
1. What scene is currently open
2. What GameObjects are in the hierarchy
3. Whether you can successfully communicate with the Unity Editor

Don't modify anything yet.

If the scene name and hierarchy Claude Code reports match what's actually open in the Editor, the full chain — Claude Code → Unity MCP → Unity Editor — is confirmed working.

First write test

Once the read-only check passes, try a small, easily-reversible write:

Using Unity MCP, create a 2D Sprite GameObject called Collectible at (0,0,0).
Make it a simple colored circle and save the current scene.

If Collectible shows up in the Unity hierarchy, Claude Code successfully modified the live Editor state through MCP — not just generated code you'd have to paste in yourself.

Initialize project instructions

Once the connection is confirmed, run /init inside Claude Code. This is the same /init command used in any Claude Code project — it generates a CLAUDE.md that Claude Code automatically reads in future sessions, so you don't re-explain your project's conventions every time.

For a Unity project, a useful first CLAUDE.md addition is telling Claude Code to prefer MCP over asking you to manually manipulate the Editor:

We're building a 2D top-down arena game.

Use Unity MCP tools whenever possible rather than asking me to manually
manipulate the editor.

For the first prototype:
- Create a simple arena
- Add a player GameObject that moves with WASD
- Add placeholder enemy GameObjects that move toward the player
- If an enemy touches the player, reduce a health value
- Add a simple health UI

Use placeholder shapes only — no art, no polish yet.
Work incrementally and check the Unity console for errors as you go.

Claude Code will read files, write scripts, run commands, and — through Unity MCP — interact with the Editor directly, typically asking permission before Editor-modifying actions unless your permission settings say otherwise.

Useful Claude Code commands while you work

A handful of core commands cover most of a Unity + Claude Code session:

For Unity specifically, claude "Use Unity MCP to inspect this project and tell me its current state." is a fast way to re-sync context at the start of a new session, since Claude Code doesn't retain memory of the live Editor state between sessions — only MCP gives it that.

Workflow tips

• Keep Unity open the whole time. Unity MCP talks to a running Editor instance; if you close the project, MCP calls will fail until it's reopened.
• Split screen it. Put Unity on one side and the terminal running Claude Code on the other, so you can watch changes land in the hierarchy in real time — that visibility is the fastest way to catch when a prompt did something unexpected.
• Start every session with a read-only inspect prompt before asking for changes, the same way you'd git status before a risky command — it confirms the connection is live and catches stale state.
• Use placeholder shapes for prototyping. Ask for primitive cubes, spheres, and colored sprites rather than final art. Iterate on mechanics with Claude Code first, then swap in real assets once the design is validated.
• Watch the Unity console. Ask Claude Code to check for compiler errors after each incremental change rather than batching a large feature and debugging blind afterward — this mirrors how Claude Code's own coding workflow recommends testing after each step rather than at the end.

Related reading

• UEFN Unreal MCP — Fortnite Verse and devices via agents (Aug 20, 2026)
• What is MCP? Model Context Protocol Complete Architecture Guide
• Claude Code Commands: Complete Slash Command Reference
• Build Your First MCP Server: Step-by-Step Guide
• How to Use Claude Connectors & MCP Servers: Complete Guide
• MCP Security Guide
• How to Build a Hop.Earth-Style AI Driving Game
• What Are Agent Skills? Complete Guide
• Official docs: Unity CLI and Anthropic's Claude Code documentation

Explore more official MCP servers and AI agent skills on explainx.ai, or check the workshops page if you'd rather learn Claude Code and MCP setup live.

Commands and CLI output in this guide reflect Unity's CLI and Claude Code as of August 2026 — check the official Unity and Anthropic documentation for the latest flag names and behavior, since MCP tooling is still evolving quickly.