Unity x Claude MCP Server

Features

20 tools covering every part of the Unity Editor:

• Scene control — create, delete, duplicate, and inspect GameObjects. Read the full hierarchy with depth control, filter by tag or component.

• Component system — add, remove, read, and modify any component. Batch-update multiple properties in a single call. Wire object references between components.

• Script generation — create MonoBehaviours, ScriptableObjects, EditorWindows from templates. Modify existing scripts with find/replace, method injection, or full rewrites.

• Asset management — search by name or type, create Materials, Prefabs, ScriptableObjects, Folders. Import and re-import assets.

• Project settings — read and write Physics, Player, Quality, Audio, Time, Graphics, Input, Tags, Editor, and Navigation settings. All changes undoable.

• Build system — build for Windows, macOS, Linux, WebGL, Android, or iOS. Development builds, custom BuildOptions.

• Editor commands — play, pause, stop, step, save, undo, redo, compile, refresh. Run any Unity menu item.

• Live C# execution — run arbitrary C# inside the editor with full access to UnityEngine and UnityEditor APIs. Compiled in-memory — no temp files, no domain reload, instant results.

Built for performance:

• Zero CPU when idle — single background thread blocked on Socket.Poll. No async, no ThreadPool, no polling loops, no timers.

• Survives domain reloads — auto-restarts after script recompilation via [InitializeOnLoad]. 5-second safety net ensures the server is always running.

• Pure C# — no external dependencies, no DLLs, no NuGet packages. Just drop the folder into your project.

Built for safety:

• Everything is undoable — all destructive operations go through Unity's Undo system. Ctrl+Z works on every change Claude makes.

• Dangerous operations blocked — execute_csharp blocks Process.Start, Environment.Exit, Registry.*, and other unsafe calls.

• Port cleanup — server registers ProcessExit and DomainUnload handlers so the port is always released.

Built for testing:

• Runtime data during Play mode — component queries automatically include live position, rotation, velocity, and sleep state for physics objects.

• Screenshot verification — capture what the camera sees, describe visible objects with screen positions, simulate clicks on objects.

• Smart snapshots — schedule timed screenshots at animation keyframes to verify visual behavior with minimum captures.

Works with:

• Claude Desktop (via stdio bridge)

• Claude Code (direct HTTP)

• Cursor (direct HTTP)

• Any MCP-compatible client

Installation

Step 1 — Add to your Unity project

Clone this repo (or download ZIP) and copy everything into your project's Packages folder:

YourProject/
  Packages/
    com.claude.unity-mcp/       ← put it here
      Editor/
      package.json
      mcp-bridge.mjs

Open Unity. The console should show:

[MCP] Ready on port 9999

Verify at Window > Claude MCP — shows server status, port, and all available tools.

Step 2 — Connect Claude

Open your Claude config file:

Add this (create the file if it doesn't exist):

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": [
        "/full/path/to/YourProject/Packages/com.claude.unity-mcp/mcp-bridge.mjs"
      ]
    }
  }
}

Shortcut: In Unity, click Window > Claude MCP > Copy Config — it copies the JSON with the correct path. Just paste it into the file.

These support direct HTTP — no bridge needed:

{
  "mcpServers": {
    "unity": {
      "url": "http://localhost:9999/mcp"
    }
  }
}

Step 3 — Add the skill files

This is what makes Claude actually good at using the tools. Without these files, Claude can connect but won't know property paths, workarounds, batch patterns, or testing workflows.

Copy SKILL.md and WORKFLOW.md into Claude's skills folder:

# macOS / Linux
mkdir -p ~/.claude/skills/unity-x-claude
cp SKILL.md WORKFLOW.md ~/.claude/skills/unity-x-claude/

# Windows (PowerShell)
mkdir -Force "$env:USERPROFILE\.claude\skills\unity-x-claude"
copy SKILL.md, WORKFLOW.md "$env:USERPROFILE\.claude\skills\unity-x-claude\"

Put them in your project's .claude/skills/ folder instead:

mkdir -p YourProject/.claude/skills/unity-x-claude
cp SKILL.md WORKFLOW.md YourProject/.claude/skills/unity-x-claude/

What these files teach Claude:

Step 4 — Restart and test

Restart Claude Desktop (or start a new chat). Try:

• "What's in my Unity scene?"

• "Create a red cube at position 0, 3, 0 with a Rigidbody"

• "Change the gravity to -20 and set the quality level to Ultra"

If Claude responds with your scene data, you're done.

Tool Reference

All tools are prefixed with unity_ (e.g., unity_get_scene). See SKILL.md for the full reference with property paths and workflow patterns.

Architecture

Claude Desktop / Claude Code / Cursor
        |
        | stdio (JSON-RPC 2.0)
        v
  mcp-bridge.mjs             Node.js — translates stdio ↔ HTTP
        |
        | HTTP POST localhost:9999/mcp
        v
  Unity Editor (MCPServer)
        |
        ├── StreamableHttpServer    Raw TcpListener, single thread, Socket.Poll
        ├── MainThreadDispatcher    ConcurrentQueue → EditorApplication.update
        ├── JsonRpcHandler          JSON-RPC 2.0 parsing
        ├── 8 Tool modules          Scene, Component, Asset, Script, Editor, Settings, Build, Execute
        └── Serialization           GameObject → JSON, Asset → JSON, Property helpers

Why zero CPU when idle

Compatibility

Troubleshooting

Contributing

Pull requests welcome. If you add a new tool, follow the pattern in Editor/Tools/ and update SKILL.md with usage examples.

License

MIT