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

Why use it

Key features

Scene and GameObject CRUD with transform controls
Component add/modify, material create/assign
EditMode + PlayMode test runner
Console log streaming
batch_execute for composing multiple tool calls atomically

Live Demo

What it looks like in practice

unity-3.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-3": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoderGamester/mcp-unity"
      ],
      "_inferred": true
    }
  }
}

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

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

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

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

VS Code → Cline → MCP Servers → Edit

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

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

~/.codeium/windsurf/mcp_config.json

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

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

~/.continue/config.json

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

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

~/.config/zed/settings.json

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

Add to context_servers. Zed hot-reloads on save.

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

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

Use Cases

Real-world ways to use mcp-unity

How to build a simple scene from chat with minimal ceremony

👤 Indie Unity devs ⏱ ~15 min beginner

When to use: You want a Unity MCP without 100+ tools cluttering your context.

Prerequisites

Unity 6 or later — unity.com/download
Node 18+ — nodejs.org or nvm
Install package from git URL — Package Manager > + > Add from git URL: https://github.com/CoderGamester/mcp-unity.git

Flow

Compose a scene

Create a new scene 'Playground'. Add a Plane, a Directional Light, and 3 cubes at positions (-2,0,0), (0,0,0), (2,0,0).✓ Copied

→ Scene appears, objects visible
Wire up interactions

Add a Rigidbody and BoxCollider to each cube. Make cube at origin kinematic.✓ Copied

→ Components visible on inspect
Run tests

run_tests mode=EditMode. Show failures.✓ Copied

→ Test output

Outcome: A working scene + passing tests, all in chat.

Pitfalls

batch_execute rollback behavior varies — not a real transaction — Assume partial success on error; verify after batch

Combine with: github

How to author and instantiate prefabs from chat

👤 Unity devs building reusable assets ⏱ ~15 min intermediate

When to use: You want the agent to maintain a prefab library.

Flow

Create a prefab

Build a GameObject 'Enemy' with Rigidbody + EnemyAI component, then create_prefab from it at Assets/Prefabs/Enemy.prefab.✓ Copied

→ Prefab file created
Instantiate

add_asset_to_scene Assets/Prefabs/Enemy.prefab at 5 random positions within 50 units of origin.✓ Copied

→ 5 enemies placed

Outcome: A reusable Enemy prefab + 5 placed instances.

How to iterate on a fix with run_tests in a tight loop

👤 Unity devs with test coverage ⏱ ~15 min intermediate

When to use: Bug + test exists; want fast red-green-refactor.

Flow

See the failure

run_tests mode=EditMode filter='EnemyAI_ShouldPatrol'. Show the stack.✓ Copied

→ Failing assertion with line
Edit and retest

Apply the minimal fix, save, and rerun the test.✓ Copied

→ Green test

Outcome: Green test, confidence in fix.

Combine with: github

Combinations

Pair with other MCPs for X10 leverage

unity-3 + github

Run tests, then commit + PR the fix

Fix EnemyAI test failure, commit on branch fix/enemy-patrol, open a PR.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
create_scene	name: str	Start a new scene	free
load_scene	path: str	Open existing scene	free
get_gameobject	name_or_id: str	Look up one object	free
update_gameobject	id, props	Rename, re-parent, toggle active	free
update_component	target, component, values	Tweak component fields	free
create_prefab	source_id, path	Capture an object as prefab	free
add_asset_to_scene	path, position?, rotation?	Instantiate an asset/prefab	free
run_tests	mode: 'EditMode'\|'PlayMode', filter?	Unit tests	free
get_console_logs	since_ms?	Check errors	free
batch_execute	calls: Call[]	Compose several tool calls	free

Cost & Limits

What this costs to run

API quota: None — local only
Tokens per call: Small; this MCP has a tight tool list
Monetary: Free (open source)
Tip: Batch related ops via batch_execute to reduce round trips.

Security

Permissions, secrets, blast radius

Minimum scopes: Local project access only

Credential storage: None

Data egress: Localhost; LLM sees whatever your tool returns

Never grant: Expose the Node bridge to non-loopback

PlayMode tests run game code — side effects possible. Commit first.

Troubleshooting

Common errors and fixes

Unity 'package could not be resolved'

Requires Unity 6 or later. Check version; git URL install fails on older editors.

Node bridge crashes on startup

Requires Node 18 + npm 9. Check 'node -v' and upgrade.

Verify: node -v

Tests don't appear

Test assemblies must be defined in Assembly Definition files referencing TestRunner.

Alternatives

mcp-unity vs others

Alternative	When to use it instead	Tradeoff
MCP for Unity (CoplayDev)	You want the largest Unity tool surface with physics/VFX coverage	More tools = more context cost
Unity-MCP (IvanMurzak)	You need Roslyn-backed one-shot C# execution	More power, more risk

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills