unity-mcp MCP — Use Cases, Install & Live Demo

Why use it

Key features

40+ granular Unity Editor tools (scene, assets, scripts, tests, physics, UI, VFX)
Safe C# script apply_text_edits with validation before write
Read the Unity console (errors/warnings) and trigger domain reloads
Run EditMode and PlayMode tests and read results
Supports multiple Unity instances with per-instance routing

Live Demo

What it looks like in practice

unity.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "unity",
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "unity": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/CoplayDev/unity-mcp"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add unity -- TODO 'See README: https://github.com/CoplayDev/unity-mcp'

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use unity-mcp

How to prototype a Unity scene from a text description

👤 Game designers, solo devs, hackathon teams ⏱ ~20 min intermediate

When to use: You want to go from 'low-poly forest with a player and 5 patrolling enemies' to a runnable scene without wiring every GameObject by hand.

Prerequisites

Unity 2021.3 LTS or newer, Python 3.10+, uv — Install uv via brew install uv; Unity from unity.com/download
Install the Unity package — Window > Package Manager > + > Add from git URL: https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

Flow

Describe the scene you want

Create a new scene called 'ForestDemo'. Add a low-poly terrain 200x200, a player capsule at origin with a rigidbody, and 5 cube enemies placed randomly between (-50,-50) and (50,50).✓ Copied

→ Scene created, GameObjects appear in Hierarchy, Unity reflects changes live
Ask for behavior scripts

Create a C# script EnemyPatrol.cs that moves between two random waypoints, and attach it to every Enemy* GameObject.✓ Copied

→ New script compiles cleanly, attached to enemies
Enter Play mode and iterate

Enter Play mode for 5 seconds, then read the console and tell me if anything threw.✓ Copied

→ Runtime log returned, Claude proposes concrete fixes for any NullReferenceException

Outcome: A runnable prototype scene with scripted enemies — under 15 minutes of chat.

Pitfalls

Script edits reject because of compile errors cascading — Ask Claude to run manage_script validate before apply_text_edits
Domain reload wipes runtime state mid-session — Save scene explicitly before script edits; use refresh_unity afterwards

Combine with: filesystem · github

How to diagnose and fix Unity compile/runtime errors from chat

👤 Unity developers stuck on a red console ⏱ ~15 min intermediate

When to use: The console is full of errors from a big refactor or a package update and you want a second pair of eyes.

Flow

Pull the console

Read the Unity console. Group errors by root cause.✓ Copied

→ Grouped error categories with likely files identified
Read the offending script

Open the top script mentioned, find the line, and explain why it breaks.✓ Copied

→ Specific fix proposal referencing line numbers
Apply a minimal patch

Apply the smallest change to make it compile, then refresh Unity and re-read the console.✓ Copied

→ Error count drops, no new errors introduced

Outcome: A green console and a diff you can review before committing.

Pitfalls

Claude proposes fixes that break API contracts for other scripts — Ask it to find references (find_in_file) before editing

Combine with: github

How to run Unity EditMode/PlayMode tests and read failures

👤 Unity devs with a real test suite ⏱ ~15 min intermediate

When to use: Before opening a PR or when CI is down and you want a quick local pass.

Flow

Kick off a test run

Run all EditMode tests in the Tests.EditMode assembly.✓ Copied

→ Test job id returned, status streamed
Summarize failures

For each failing test, show the assertion message and the line it fired on.✓ Copied

→ Per-test diagnosis
Fix the smallest failure first

Pick the failure most likely caused by my last change and propose a patch.✓ Copied

→ Concrete edit suggestion

Outcome: A green test run with traceable edits.

Pitfalls

PlayMode tests need a different assembly — Specify EditMode vs PlayMode explicitly

Combine with: github

Combinations

Pair with other MCPs for X10 leverage

unity + github

Scaffold a scene + scripts, commit the changes, open a PR for review

Build the EnemyPatrol feature in Unity, commit the new script and scene changes to a branch 'feature/enemy-patrol', and open a PR with a summary of what changed.✓ Copied

unity + filesystem

Import a batch of 3D assets from a local folder and wire them into prefabs

Read /Downloads/kenney-nature-pack, import every .fbx into Assets/Models/, then create a prefab for each tree with a collider.✓ Copied

unity + unity-2 + unity-3

Pick the Unity MCP that best matches your workflow — run only one at a time

Compare MCP for Unity vs CoderGamester mcp-unity for my 2D tilemap project, then keep the better one enabled.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
manage_scene	action: 'create'\|'open'\|'save'\|'load', name?: str, path?: str	Any scene lifecycle change	free
find_gameobjects	query: str, scene?: str	Locate objects by name, tag, or component	free
manage_components	target: str, action: 'add'\|'remove'\|'modify', component: str, values?: obj	Attach or tweak components	free
manage_script	action: 'create'\|'read'\|'delete', path: str, body?: str	Full-file script writes — use apply_text_edits for partial	free
apply_text_edits	path: str, edits: Edit[]	Surgical patches; safer than full rewrites	free
read_console	since_ms?: int	Inspect errors/warnings after any change	free
run_tests	mode: 'EditMode'\|'PlayMode', filter?: str	Start a test run; poll with get_test_job	free
refresh_unity		After creating/modifying scripts or assets	free
manage_asset	action, path, ...	Import/move/delete assets	free
unity_docs	query: str	Look up Unity API docs inline	free

Cost & Limits

What this costs to run

API quota: No remote API — runs entirely on your machine
Tokens per call: Reading the scene hierarchy: 500–3000 tokens. Script reads: depends on file size
Monetary: Free (open source, MIT)
Tip: Disable tools you won't use (e.g. manage_vfx, manage_probuilder) via the tool allowlist to shrink the prompt footprint.

Security

Permissions, secrets, blast radius

Minimum scopes: local filesystem write to your Unity project

Credential storage: None required — localhost HTTP only

Data egress: Localhost only (http://localhost:8080/mcp). No telemetry by default.

Never grant: access to Unity projects outside the active one

AI-driven script edits can break your project — commit before long sessions.
run_tests in PlayMode executes game code; treat it like 'play' would, with full side effects.

Troubleshooting

Common errors and fixes

Claude can't connect: ECONNREFUSED localhost:8080

Unity Editor must be open with the MCP package loaded. Check Window > MCP for Unity > Status.

Verify: curl http://localhost:8080/mcp/ping

apply_text_edits reports 'file changed on disk'

Another tool modified the file. Re-read with manage_script before editing again.

refresh_unity hangs forever

Usually a compile error locking the domain reload. Open Unity, fix the red script, then retry.

Verify: Check Unity console manually

Package Manager 'Could not resolve git URL'

Behind a proxy or no git on PATH. Install git and retry, or use OpenUPM install instead.

Verify: git --version

Alternatives

unity-mcp vs others

Alternative	When to use it instead	Tradeoff
Unity-MCP (IvanMurzak)	You want CLI-driven setup and Roslyn-based C# execution	Smaller community than Coplay's, different tool surface
mcp-unity (CoderGamester)	You want a simpler tool set focused on scene manipulation and tests	Fewer tools, less coverage of materials/VFX

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills