How to use Claude Code with Unity

Short answer: point Claude Code at your Unity project folder, keep the Editor open, and let it edit C# under Assets/. Unity recompiles, you (or Claude) read the Console and fix errors, then you run tests. Unity MCP and Unity's official Claude Code plugin are optional helpers for Editor control and Unity-specific skills. Everything below comes from Unity and Anthropic docs, checked October 19, 2026.

What you are connecting

Three official pieces matter for this guide (plus one popular community option):

• Claude Code (Anthropic). A coding agent in the terminal or desktop app that reads and edits your project files. It needs a paid Claude plan or API Console access. Docs: Claude Code quickstart.
• Unity's official plugin for Claude Code. First-party skills (UI, 2D, URP, audio, and more) plus Unity CLI wiring. Install with /plugin marketplace add Unity-Technologies/unity-agent-plugin then /plugin install unity@unity-agent-plugin. Unity's plugin docs say the plugin ships skills and does not itself run an MCP server; Editor control skills use the Unity CLI. Docs: Unity plugin for Claude Code.
• Unity MCP (official). An MCP bridge so an external agent can call Editor tools (scenes, GameObjects, console). Needs Unity 6 (6000.0)+ and com.unity.ai.assistant. Unity's public FAQ says the MCP server is free and does not consume Unity AI credits. Docs: Get started with Unity MCP.
• Community option: CoplayDev/unity-mcp (MIT). Community-maintained MCP for Unity 2021.3 through 6.x. Not affiliated with Unity Technologies. Use it if you need MCP on an older Editor, or prefer its tool set. Label it clearly as community software.

Unity is also retiring the umbrella brand name "Unity AI" and talking about each tool by name: in-editor assistant, AI gateway, MCP server, official plugin, and CLI (unity.com/features/ai).

What you need

• Unity 6.0 or newer for official MCP and the official Claude Code plugin. Download from unity.com/download via Unity Hub. Older versions still work with the file edit loop.
• Claude Code, signed in. Free Claude.ai does not include it.
• Git (strongly recommended) so you can undo a bad agent change.
• Bash on Windows if you use AI gateway with Claude Code inside the Editor. Unity's gateway docs note Claude Code on Windows needs Git Bash.

The realistic workflow (MCP optional)

1. Claude Code edits C# directly under Assets/ (and sometimes asmdef or test folders).
2. Keep the Unity Editor open on that project so scripts recompile and show errors in the Console.
3. Read the Console / Editor log. Paste errors back to Claude, or connect MCP later so it can call Unity_ReadConsole.
4. Run tests with Unity Test Framework in batch mode (Edit Mode is the usual starting point).
5. Fix and repeat. One small feature at a time.
6. Playtest yourself. No agent can judge feel or fun for you.

This matches how many people actually ship with agents in Unity: files first, Editor open, tests for regressions, MCP only when you need live scene control.

Setup, step by step

1. Create a Unity project

In Unity Hub, install a Unity 6.0+ Editor, create a 2D or 3D project, and put it in its own folder. Open it once so Unity generates Assets/, ProjectSettings/, and .meta files.

2. Install Claude Code and sign in

From Anthropic's quickstart (macOS, Linux, WSL):

curl -fsSL https://claude.ai/install.sh | bash

Then:

cd /path/to/YourUnityProject
claude

Sign in when prompted. Claude Code requires Pro, Max, Team, Enterprise, or Console. Pro is $20/mo monthly ($17/mo billed annually), per claude.com/pricing (October 2026). Confirm claude --version works.

3. Add a project CLAUDE.md

Anthropic loads CLAUDE.md (or .claude/CLAUDE.md) at the start of each session so Claude remembers project rules. Put one at the project root. Example you can paste and edit:

# Unity project notes

- Engine: Unity 6 (edit this to match your exact version, e.g. 6000.0).
- Scripts live under Assets/Scripts/. Prefer MonoBehaviour components over Editor-only code unless asked.
- Keep scenes and prefabs simple. Prefer editing .cs files; scene YAML changes are easy to break.
- After script edits, wait for the Editor to recompile, then read the Console for errors.
- Tests: Edit Mode tests under Assets/Tests/EditMode/. Run with:
  Unity -batchmode -runTests -projectPath . -testPlatform EditMode -testResults TestResults.xml -logFile -
- Do not delete or rewrite .meta files. Commit .meta with new assets.
- Ask before changing Project Settings, Packages, or Input System bindings.

Keep it short and concrete. Run /init in Claude Code if you want it to draft a starting file from the repo, then trim anything wrong.

4. Git and .meta tips

Initialize git before you let the agent roam. Commit working steps often. A minimal Unity .gitignore looks like this (adapt from Unity's own docs or community templates; do not ignore *.meta):

# Unity generated
/[Ll]ibrary/
/[Tt]emp/
/[Oo]bj/
/[Bb]uild/
/[Bb]uilds/
/[Ll]ogs/
/[Uu]ser[Ss]ettings/
*.csproj
*.unityproj
*.sln
*.user
*.pidb
*.booproj
*.svd
*.pdb
*.mdb
*.opendb
*.VC.db

Always commit .meta files with new scripts and assets. Those GUIDs keep scene and prefab references from breaking on another machine.

Your first tiny project loop

1. Ask Claude Code: Create Assets/Scripts/PlayerController.cs: a 2D Rigidbody2D player that moves with WASD or arrow keys. Add a short comment at the top explaining how to attach it.
2. In the Editor, create a Capsule or Sprite, add Rigidbody2D, attach the script, press Play. If compile errors appear, paste the Console text into Claude Code.
3. Ask: Add an Edit Mode test assembly under Assets/Tests/EditMode that checks a pure C# helper (for example clamp move speed). Keep Play Mode tests for later.
4. Run tests from a terminal (path to the Unity binary differs by OS; on macOS it is often inside Unity.app). Flags verified against Unity Test Framework 1.4 command-line docs:

Unity -batchmode -runTests -projectPath /path/to/YourUnityProject -testPlatform EditMode -testResults TestResults.xml -logFile -

Notes from those docs: -batchmode avoids UI prompts; -testPlatform EditMode runs Edit Mode tests (default is Edit Mode if you omit it); results write as NUnit XML. Do not expect the agent to "feel" whether movement is fun. That is your playtest job.

5. Add one feature at a time: a coin, a score, a simple enemy. Repeat edit, Console, test, play.

Optional: Unity's official Claude Code plugin

Inside a Claude Code session:

/plugin marketplace add Unity-Technologies/unity-agent-plugin
/plugin install unity@unity-agent-plugin

Pick user, project, or local scope when asked. Verify with /unity: or /plugin. Unity's docs say skills that drive the Editor need the Unity CLI installed, the Pipeline package in the project (unity pipeline install), and the Editor open. Check unity status. For the separate MCP server they mention unity mcp configure.

Optional: connect official Unity MCP

1. Open the project in Unity 6+ with com.unity.ai.assistant installed (AI button in the toolbar, or Package Manager).
2. Go to Edit, Project Settings, AI, Unity MCP Server. Confirm Unity Bridge shows Running.
3. Under Integrations, select Claude Code and Configure, or copy the Example Configuration JSON.
4. Approve the first Pending Connection with Allow.
5. In Claude Code, run /mcp and look for the Unity server. Try: Read the Unity console messages and summarize any errors.

Manual stdio style config (paths from Unity MCP docs; expand ~ to an absolute home path because some clients do not expand tildes):

{
  "mcpServers": {
    "unity-mcp": {
      "command": "/Users/YOU/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64",
      "args": ["--mcp"]
    }
  }
}

Platform relay paths from the same docs: macOS Apple Silicon ~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64, macOS Intel relay_mac_x64, Windows %USERPROFILE%\\.unity\\relay\\relay_win.exe, Linux ~/.unity/relay/relay_linux. Always pass --mcp.

You can also add a stdio server with Anthropic's CLI pattern claude mcp add (see Claude Code MCP docs). Prefer the JSON Unity prints in Project Settings so the relay path matches your machine.

Optional: AI gateway (Claude inside the Editor)

If you want Claude Code routed from Unity's Assistant window, Unity's AI gateway docs (Assistant package 2.17.0-pre.1) say: install the Assistant package, open Project Settings, AI, Gateway, pick Claude Code (2.1.45 or later), and set ANTHROPIC_API_KEY. Those docs also say gateway and MCP access need an eligible Unity subscription and an assigned seat, while in-editor assistant credits alone do not. Unity's marketing FAQ separately says using a third-party agent via the gateway does not consume Unity credits. If Project Settings blocks you, check org seat assignment first.

Optional: community CoplayDev unity-mcp

CoplayDev/unity-mcp is community-maintained (MIT), supports Unity 2021.3 LTS through 6.x per its README, and is not from Unity Technologies. Install path from its docs: Package Manager, Add from git URL:

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

Then use Window, MCP for Unity to configure clients. Prefer Unity's official MCP on Unity 6 when you can; use Coplay when you need older Editor support or its specific tools.

Common pitfalls

• Editor closed. Recompile and many MCP or CLI actions need a running Editor on that project.
• Editing scenes as text blindly. YAML scenes and prefabs break easily. Prefer script and component changes, then tweak the scene in the Editor.
• Deleting .meta files. Broken references look like "missing script" forever. Commit metas; never let the agent "clean them up."
• Huge one-shot prompts. Ask for one script or one bug fix. Review the diff.
• Assuming MCP is required. File edit plus Console plus tests is enough for most beginner games.
• Mixing Muse docs. Unity Muse is deprecated. Current tools are the in-editor assistant, gateway, MCP, plugin, and CLI.
• Seat / trial confusion. MCP and the official plugin are described as free on unity.com/features/ai; the credit-based in-editor assistant is the paid piece for Personal after trial. Package docs may still mention seats for gateway/MCP in orgs. If something is greyed out, read the Project Settings message rather than guessing.

Sources (checked October 19, 2026)

• Unity's AI tools (unity.com/features/ai)
• Unity AI tools beta overview (Unity blog, May 5, 2026)
• Get started with Unity MCP (Assistant 2.16 docs)
• Configure AI gateway (Assistant 2.17 docs)
• Unity's plugin for Claude Code
• Unity Test Framework command-line reference 1.4
• Claude Code quickstart, MCP, CLAUDE.md memory
• Claude pricing
• CoplayDev/unity-mcp (community)

Related

Using Unreal instead? Follow How to use Claude Code with Unreal Engine. Choosing an agent? Read Claude Code vs Codex vs Cursor for game dev. Choosing an engine? See Godot vs Unity for beginners or browse coding and game logic tools.

FAQ

Is Claude Code free?

No. Anthropic's Claude Code docs say you need a Pro, Max, Team, Enterprise, or Console (API) account. The free Claude.ai plan does not include Claude Code. Claude Pro is $20/mo if billed monthly ($17/mo when billed annually at $200), checked on claude.com/pricing in October 2026.

Does this work with Unity Personal?

Yes for the file edit workflow: Claude Code writes C# under Assets/, and Unity Personal can open that project. Unity's public AI FAQ says the MCP server, CLI, and official plugin are free to use with no Unity AI credit cost. The in-editor AI assistant is different: Personal users get a free trial, then $10/mo, while Pro, Enterprise, and Industry include it. Always re-check unity.com/features/ai.

Do I need Unity MCP?

No. The main loop is edit scripts, keep the Editor open so it recompiles, read the Console, run tests, fix and repeat. MCP is optional when you want the agent to inspect scenes, GameObjects, or the Console through tools.

Claude Code vs Unity's in-editor AI Assistant?

Claude Code runs in your terminal (or desktop app) and edits project files on disk. Unity's in-editor assistant is a chat panel inside the Editor with Ask, Plan, and Agent modes, and it uses Unity AI credits (or AI gateway with your own key). You can use either, or both. The official Unity plugin for Claude Code adds Unity skills; it does not replace the in-editor assistant.

Which Unity version do I need for official MCP?

Unity's MCP get-started docs require Unity 6 (6000.0) or later with the com.unity.ai.assistant package. The official Claude Code plugin docs also say Unity 6.0 or later. Older editors can still use the file edit workflow, or a community MCP such as CoplayDev unity-mcp (Unity 2021.3+ per its README).

Should I commit .meta files?

Yes. Unity creates a .meta file for every asset. Commit them with your scripts so GUID references stay stable across machines. Ignore Library/, Temp/, Obj/, Logs/, and UserSettings/ in git.