Unity MCP — Control Unity Editor from Any AI Assistant

_STATUS

_SPEC

_STACK

Let any MCP-compatible AI assistant control your Unity Editor — inspect scenes, edit GameObjects, run playtests, and capture screenshots without leaving the chat. JSON-framed TCP protocol; batch delivers 80–95% token savings (5–20× compression) on multi-step work.

_{MCP (Model Context Protocol) is Anthropic's open standard for giving AI assistants structured tool access.}

Why Unity MCP?

• Stop alt-tabbing. Your AI assistant inspects your scene, edits components, runs playtests, and captures screenshots without you leaving the chat.
• Stop burning tokens on boilerplate. Each batch call replaces 5–20 individual round-trips — 80–95% fewer tokens on the same work.
• Stop writing glue code. Registered tools cover scene CRUD, animation, VFX, UI, shaders, runtime control, and code intelligence — with a plugin seam for your own.

Two ways to work

🖥️ CLI Mode — run from terminal via Claude Code, Codex CLI, or any MCP client. The Python server connects to Unity over TCP :9500. Best for automation, batch operations, and scripting. Full access to 120 MCP tools with 80–95% token compression.

💬 In-Unity Chat — open MCP → Chat inside the editor. No API key needed — spawns the CLI directly. 5 backends: Claude, Antigravity, Kimi, Codex, OpenCode. Drag GameObjects, scripts, and materials into chat as typed context chips. Each AI turn gets its own undo group — one Ctrl+Z rolls back everything the AI changed. Domain-reload safe. Extensible chip-kind registry lets third-party plugins add new chip types with zero core edits.

Before / after — creating and configuring 3 objects:

# Before: 9 separate MCP calls (~1800 tokens)
create_object("Enemy")
set_property("Enemy", "Transform", "position", "0,1,0")
manage_component("Enemy", "Health", "add")
set_property("Enemy", "Health", "maxHp", "100")
# ... 5 more calls

# After: 1 batch call (~120 tokens, 93% savings)
batch("""
create_object name=Enemy
set_property path=Enemy component=Transform prop=position value=0,1,0
manage_component path=Enemy type=Health action=add
set_property path=Enemy component=Health prop=maxHp value=100
""")

What you can say

"Create a player character with health component and position it at the center of the scene"

"Find all enemies without colliders and add BoxCollider to each"

"Take a multi-view screenshot and compare it with the last one"

"Run a playtest: move the player to the door, wait for it to open, assert the score increased"

"Show me what changed since my last checkpoint"

Architecture

Quick Start

Prerequisites: Python 3.10+ · Unity 6000.0+ · TCP port 9500 free

One-liner (macOS/Linux):

curl -fsSL https://raw.githubusercontent.com/german-krasnikov/unity-kiss-mcp/master/install/bootstrap.sh | bash

One-liner (Windows PowerShell):

iex (iwr https://raw.githubusercontent.com/german-krasnikov/unity-kiss-mcp/master/install/bootstrap.ps1).Content

Windows: antivirus blocked the script?

Option 1: Install via install.py

1. Install uv:

   winget install astral-sh.uv

2. Clone the repo:

   git clone https://github.com/german-krasnikov/unity-kiss-mcp.git "$HOME\.unity-mcp\server"
   cd "$HOME\.unity-mcp\server"

3. Run setup:

   uv run python install.py setup

4. Configure your AI tool:

   uv run python install.py configure --tool claude-code

Option 2: Manual setup

1. Install uv: Open PowerShell and run:

   winget install astral-sh.uv

2. Add the Unity plugin via Package Manager → Add package from git URL:

   https://github.com/german-krasnikov/unity-kiss-mcp.git?path=unity-plugin
   

3. Configure your AI tool manually (see "Manual MCP configuration" above).

4. Open the Setup Wizard in Unity via MCP → Setup Wizard to complete setup.

Manual MCP configuration (all AI tools)

Add this to your MCP config file:

{
  "mcpServers": {
    "unity-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/german-krasnikov/unity-kiss-mcp.git#subdirectory=server", "unity-mcp"],
      "env": { "UNITY_MCP_PORT": "9500" }
    }
  }
}

AI Tool	Config file path
Claude Code	~/.claude.json
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json (macOS/Linux) or %APPDATA%\Codeium\windsurf\mcp_config.json (Windows)
Kimi	~/.kimi-code/mcp.json
VS Code	~/Library/Application Support/Code/User/mcp.json (macOS), %APPDATA%\Code\User\mcp.json (Windows), or ~/.config/Code/User/mcp.json (Linux)
OpenCode	~/.config/opencode/opencode.json (macOS/Linux) or %APPDATA%\opencode\opencode.json (Windows)
Codex	~/.codex/config.toml

Without uvx: replace "command": "uvx", "args": ["--from", "git+...", "unity-mcp"] with "command": "python", "args": ["-m", "unity_mcp.server"]

Manual setup:

1. Python server: uvx --from git+https://github.com/german-krasnikov/unity-kiss-mcp.git#subdirectory=server unity-mcp — zero-install, runs on demand from GitHub (no separate install step).
2. Add the Unity plugin via Package Manager → Add package from git URL:

   https://github.com/german-krasnikov/unity-kiss-mcp.git?path=unity-plugin
   

3. Open Unity, then open the Setup Wizard via MCP → Setup Wizard menu. It will:
   • Auto-detect installed AI tools (shows "detected" badge)
   • One-click configure: pick your tool → choose Global or Project scope → done
   • Supports 9 backends: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex, Kimi, OpenCode, Antigravity

Alternative: full local clone

git clone https://github.com/german-krasnikov/unity-kiss-mcp.git
cd unity-kiss-mcp
python install.py setup
python install.py configure --tool claude-code
python install.py doctor

This clones the repo, creates a venv, installs dependencies, configures your AI tool, and verifies the setup. Supported tools: claude-code, claude-desktop, cursor, windsurf, vscode, codex, kimi, opencode

Compatibility

Component	Tested	Minimum
Unity	6000.3	6000.0 (Unity 6)
Python	3.12	3.10
OS	macOS	macOS, Windows, Linux
Claude Code	latest	any with MCP support
Codex CLI	latest	any with MCP support
Claude Desktop	latest	any with MCP support

Features

• Token Optimization — batch compresses 5–20 calls into one (80–95% savings), deferred tool schemas, per-session cost analytics
• In-Unity Chat — 5 CLI backends (Claude, Antigravity, Kimi, Codex, OpenCode), no API key needed, typed context chips ([hierarchy:/Player], [script:Health.cs]), per-turn undo, domain-reload safe
• Code Intelligence — Roslyn-powered find_references, compile_preflight, semantic_at
• PlayTest DSL — 21 commands: MOVE, ASSERT, WAIT_UNTIL, INVOKE, SNAPSHOT, SIMULATE
• Multi-Scene Management — Load multiple scenes, inspect/edit across scenes, move/copy objects between loaded scenes, unified object_diff for cross-scene comparison
• Scene CRUD & Tools — scene actions (open_additive, close, set_active, list), hierarchy inspection, query syntax, diff tracking, checkpoint/restore
• Animation & Timeline — clips, key management, Timeline assets, Animator states/transitions
• VFX & Particles — particle system CRUD, 11 module presets, shader graph integration
• Multi-View Screenshots — 4-panel grid (Front/Left/Top/Iso), bounding-box overlay, visual regression
• Multi-Project Ports — each Unity project auto-assigns a unique TCP port (9500–9599), CLI and Chat get isolated slots
• Capability Gating — TIER1 core always on; 8 category toggles per-session
• Cross-Platform — Windows, macOS, Linux — binary resolution, lockfile, and venv per platform
• Plugin Extensibility — register your own tools in one file, no cross-imports

PlayTest DSL example

run_playtest(script="""
MOVE /Player TO 5,0,3
WAIT_UNTIL /Enemy|Health|hp <= 0 timeout=5
ASSERT /Player|Health|hp > 0
ASSERT_CONSOLE_CLEAN
SNAPSHOT /Player /Enemy
""")

Add your own tool — one file, zero cross-imports

# server/src/unity_mcp/tools/my_tool.py
def register(mcp, send, args):
    @mcp.tool()
    async def find_inactive(path: str = "/") -> str:
        """Find all inactive GameObjects under path."""
        return await send("find_objects", args(path=path, active="false"))

Drop the file in tools/ and add it to tools/__init__.py — it registers on next server start.

Recent Changes

_{Full history: CHANGELOG.md}

v0.67.0 — 2026-06-29 — **ThinView Flag Removed** — Deleted MCPChat.ThinView conditional compilation …

ThinView Flag Removed — Deleted MCPChat.ThinView conditional compilation flag (−7410 LOC).

v0.66.0 — 2026-06-28 — **FIX-1: Cross-Assembly Compile Error Detection (diagnose tool)** — …

FIX-1: Cross-Assembly Compile Error Detection (diagnose tool) — DiagnoseCommand now hooks CompilationPipeline.assemblyCompilationFinished …

v0.65.1 — 2026-06-27 — **Plugin Development Guide** — New `/docs/plugin-development.md` (2100+ lines).

Plugin Development Guide — New /docs/plugin-development.md (2100+ lines).

v0.65.0 — 2026-06-27 — **Python run_tests Pre-Flight Gate** — `diagnose(expected_compile=False)` …

Python run_tests Pre-Flight Gate — diagnose(expected_compile=False) blocks test execution if compilation unstable.

v0.64.0 — 2026-06-27 — **T1: Bare-Name Chip Detection** — `SceneObjectNormalizer._resolver?.Refresh()` …

T1: Bare-Name Chip Detection — SceneObjectNormalizer._resolver?.Refresh() in OnSend with null-safe delegate guard.

Older releases

• v0.63.0 — 2026-06-27 — IToolbarButtonProvider.MenuOnly DIM — New default interface member `bool …
• v0.62.0 — 2026-06-26 — Error Resolver Toolbar — Chat toolbar button ("Fix Errors") for …
• v0.61.0 — 2026-06-26 — PerfOverlay — SceneView UITK overlay showing real-time FPS sparkline, …
• v0.60.0 — 2026-06-26 — profile MCP Tool — Session-based frame recording (burst/manual modes) with …
• v0.59.0 — 2026-06-26 — Runtime Code Execution in Play Mode — execute_code removed `mutating: …
• v0.58.0 — 2026-06-25 — ask tool Scene Queries — Extended UNITY_NOUNS_RE with 23 …
• v0.57.0 — 2026-06-24 — Tool-Gating OR Bug — Empty disabled set was falsy, skipping the entire tool …
• v0.56.0 — 2026-06-24 — Unified Scene View Overlay — Merged 2 separate overlays …
• v0.55.0 — 2026-06-24 — Chat sees 3rd-party MCP from CLI global configs — Claude Code, Codex, Kimi, …
• v0.54.1 — 2026-06-23 — Focus-Loss CPU Storm (Multi-Unity × Multi-CLI) — Fixed 1000% CPU spike when …
• v0.53.1 — 2026-06-23 — Codex App-Server Elicitation Hang — Fixed infinite spinner on mutating MCP …
• v0.53.0 — 2026-06-23 — Reconnect stability — Exponential backoff (5→60s) on failed reconnects + …
• v0.52.6 — 2026-06-22 — Multi-Unity Port Race Conditions — Fixed port file collision and …
• v0.52.5 — 2026-06-22 — Auto-discard dirty scene on quit — removed opt-in toggle, now always active.
• v0.52.0 — 2026-06-21 — Arcade Animation System — Unified animation primitives for consistent UI …
• v0.51.0 — 2026-06-21 — Scene Annotation Primitives — Expanded RegionTool with 3 new annotation …
• v0.50.3 — 2026-06-21 — Unstructured MCP Output — Introduced _UnstructuredMCP(FastMCP) subclass …
• v0.50.2 — 2026-06-21 — WizardConfigWriter visibility — changed class and GitInstallUrl from …
• v0.50.1 — 2026-06-21 — Update Cache Loop — UpdateChecker now clears EditorPrefs cache after …
• v0.50.0 — 2026-06-21 — Wizard Fallback — Setup Wizard detects missing backends (e.g., no Claude …
• v0.47.0 — 2026-06-21 — Replaces USD cost display with input/output token counts + context window fill %
• v0.46.0 — 2026-06-21 — Polygon2D — Immutable 2D polygon (XZ plane), winding-number …
• v0.45.0 — 2026-06-20 — InstallSourceDetector — Detects file: (local Git clone) vs git: (UPM …
• v0.44.1 — 2026-06-20 — Fix: Codex Windows path crash — TOML command now uses literal strings …
• v0.44.0 — 2026-06-20 — LevelUpPanel: 4-state machine (Idle→Animating→Done→Diff) with XP bar + sparkles …
• v0.43.0 — 2026-06-20 — Remove tundra.digestcache deletion (SIGABRT in RegisterAssemblyDefinition)
• v0.42.0 — 2026-06-20 — Setup Wizard One-Button Install — 3-screen flow (Welcome → PickBackend → …
• v0.41.4 — 2026-06-20 — @Mention Autocomplete — Type @ in Chat input to trigger autocomplete …
• v0.41.0 — 2026-06-20 — Session Handoff (Chat↔CLI) — Button "→ CLI" in Chat copies resume command …
• v0.40.1 — 2026-06-19 — Fix: Chat duplicate TCP connections — Claude Chat no longer spawns …
• v0.40.0 — 2026-06-19 — One-Liner Installation — curl | bash (macOS/Linux) or iex (iwr).Content …
• v0.38.0 — 2026-06-19 — External MCP Server Support in Chat:
• v0.37.0 — 2026-06-18 — Bridge Stability & Reload Recovery (v0.36.0):
• v0.36.0 — 2026-06-18 — Media Preview Redesign:
• v0.35.0 — 2026-06-17 — Inline Media Preview Bubbles — Phase 2 lazy-load media panel in chat:
• v0.34.6 — 2026-06-17 — Binary Resolver — macOS zsh PATH sourcing — Changed bash -lc to `zsh …
• v0.34.0 — 2026-06-17 — Plugin Extensibility API — New public interfaces for plugins to extend chat …
• v0.33.0 — 2026-06-16 — Codex Silent Abort Fix (Plugin v0.33.0) — Fixes hung turns when Codex tools …
• v0.32.0 — 2026-06-16 — run_tests Fire-and-Forget Protocol (Server v0.32.0) — run_tests(mode) now …
• v0.31.1 — 2026-06-16 — run_tests Domain Reload Disconnect Recovery (Server v0.31.1) — Fixes silent …
• v0.31.0 — 2026-06-16 — Security Hardening (Gate A: release blocker) — CodeExecutor.SecurityScan …
• v0.30.4 — 2026-06-16 — Per-Backend Model Selector (Plugin v0.30.4) — Dropdown in MCPChatWindow …
• v0.30.3 — 2026-06-16 — Gemini CLI Backend (Plugin v0.30.1, v0.30.2, v0.30.3) — Third CLI backend …
• v0.29.38 — 2026-06-15 — Codex Interactive User Input (Plugin v0.29.38) — Codex CLI can now show …
• v0.29.37 — 2026-06-15 — Claude Interactive User Input (Plugin v0.29.37, Server) — Claude CLI …
• v0.29.11 — 2026-06-15 — Interactive Permission Protocol Fix (Plugin v0.29.11, Sprint 1C) — Fixes …
• v0.29.2 — 2026-06-15 — Chat Assembly Split (Plugin v0.29.2) — UnityMCP.Editor.Chat split into …
• v0.27.4 — 2026-06-14 — Reload Recovery Package (Plugin + Server v0.27.4) — Independent UPM package …
• v0.26.0 — 2026-06-13 — Test Quality Audit (Server + Plugin v0.26.0) — Systematic cleanup of test …
• v0.25.13 — 2026-06-12 — UTF-8 Encoding Round-3 (Server + Plugin v0.25.13) — **(C1: Python test I/O …
• v0.25.12 — 2026-06-12 — UTF-8 Everywhere (Server + Plugin v0.25.12) — (Round 1) Python file I/O …
• v0.25.0 — 2026-06-12 — Multi-Scene CRUD + Diff (Plugin v0.25.0) — Cross-scene transfer_object …
• v0.24.1 — 2026-06-12 — Port Re-Discovery on Reconnect (Server v0.24.1) — UnityBridge now …
• v0.24.0 — 2026-06-12 — Multi-Scene Hierarchy Support (Plugin v0.24.0) — get_hierarchy now …
• v0.23.13 — 2026-06-11 — SettingsNavController Hardening (Plugin v0.23.13) — Timer-based animated …
• v0.23.0 — 2026-06-11 — **Reconnect Recovery: Zombie Detection + SO_REUSEPORT + TCP Probe (Server + …
• v0.22.1 — 2026-06-11 — Crash Logging for Unhandled Server Exceptions — Python MCP server now …
• v0.22.0 — 2026-06-11 — Multi-Project Port Configuration (Plugin + Server v0.22.0) — Unity projects …
• v0.21.0 — 2026-06-11 — Cross-Platform Windows/Linux Support (Plugin v0.21.0 + Server) — Plugin now …
• v0.20.7 — 2026-06-10 — Reload-resume re-sends the full-path chip payload, not short-name mentions (task#10)
• v0.20.6 — 2026-06-10 — Full-path chip payload + always-raw "Show LLM payload" inspector for every turn type
• v0.20.0 — 2026-06-10 — Chip-unification Phase 1 — delete SceneNameLinker path, unified @-mention rendering
• v0.19.2 — 2026-06-10 — Chat reload double-bubble MAJOR + drag-drop crash guard + clean test console
• v0.19.1 — 2026-06-10 — P0/P1 chat UX hardening — ResetTurnFlags DRY, bubble dedup, backend restore race
• v0.19.0 — 2026-06-10 — Chat UX F27–F30 — Domain reload + external drag/drop + input height + backend cleanup
• v0.18.0 — 2026-06-10 — Chat UX F20–F26 — Stop button, reload survival, AutoScroll, dropdown persist, @Object dedup, direct Clear, drag/drop MonoScript
• v0.17.36 — 2026-06-06 — Settings Hub redesign — central hub UI + circuit-node header animation + Claude foldout grouping
• v0.17.34 — 2026-06-06 — F25 Phase 2 settings hub — unique thematic header animations per sub-window
• v0.17.28 — 2026-06-06 — F23 settings split — 3 focused EditorWindows + Chat event hook
• v0.17.20 — 2026-06-06 — 40-architect test audit — 299 new tests total, 3 P0+P1 bug fixes
• v0.17.18 — 2026-06-06 — F20–F22 bugfixes — select-all, @mention search, orphan bold
• v0.17.17 — 2026-06-05 — F15a-F19 chip redesign — linker disable, leading-space guard, context menus
• v0.17.14 — 2026-06-05 — F13–F14 inline-chip architecture + bare-name normalizer + review fixes
• v0.17.2 — 2026-06-05 — inline context chips + review fixes (regex + staleness + test DRY)
• v0.17.0 — 2026-06-05 — full-project code review sprint — 12 waves of fixes across Python + C#
• v0.16.0 — 2026-06-05 — F12 chat UX overhaul — composed inline-chip field + response pills + session clear
• v0.15.8 — 2026-06-05 — inline-chips + extensible chip-kind registry — F11
• v0.15.0 — 2026-06-04 — chat UX polish sprint — F1–F10 + review-hardening
• v0.14.0 — 2026-06-04 — multi-backend agent chat — Claude + Codex via DRY CliBackendBase
• v0.7.1 — 2026-06-04 — tech-debt sprint wave 1–3 (Python/C#/Chat) — pure quality
• v0.7.0 — 2026-06-04 — Editor.log out-of-band corroboration — P0 compile-tool blindness fix
• v0.6.1 — 2026-06-04 — atomic batch rollback — transactional scene edits
• v0.5.0 / 0.12.0 — 2026-06-04 — scoped scene queries — search_scene root+limit + spatial center
• v0.11.0 — 2026-06-04 — per-turn undo rollback + Restore button
• v0.10.0 — 2026-06-04 — chat plan/act approve & execute + slash templates
• v0.9.0 — 2026-06-04 — chat context resolution + compile gating tool
• v0.8.0 — 2026-06-04 — compile auto-fix + editor-state injection + tool ping
• v0.7.0 — 2026-06-04 — F4 deferred schema + reload-survival + auto-selection
• v0.6.0 — 2026-06-03 — Aura pill + native theme + perms gating
• v0.5.0 — 2026-06-03 — chat UX polish — refs, grouping, scroll
• v0.4.0 — 2026-06-03 — extensible render: md + mermaid + img
• v0.3.0 — 2026-06-03 — in-Unity Agent Chat + UIToolkit status
• v0.2.6 — 2026-06-02 — tool-gating fix + settings UI

Documentation

User Guides & Troubleshooting: docs/README.md

• Installation guides for macOS, Windows, Linux
• Troubleshooting TCP connection issues
• MCP configuration for all AI tools
• Chat feature reference (context chips, undo, domain-reload safety)
• PlayTest DSL tutorial with examples
• Multi-scene workflows
• Animation, VFX, and shader graph integration

Developer Reference:

• Architecture & Design: AI/architecture.md — high-level system design, component responsibilities, serialization formats, test organization
• MCP Tool Catalog: AI/mcp-server.md — complete tool reference with signatures, examples, and token costs
• Token Optimization: docs/tools/batch.md — batch patterns, deferred schemas, per-session cost analytics
• Multi-Scene Guide: .claude/skills/multi-scene.md — cross-scene queries, path resolution, component serialization

FAQ

How is this different from Unity 6.2's built-in AI assistant?

Unity's built-in AI is limited to code generation. Unity MCP gives full editor control: scene CRUD, animation, VFX, playtesting, screenshots. 99 tools vs basic code completion.

Does this work with Unity 5 / Unity 2022?

No, requires Unity 6000.0+ (Unity 6). Uses modern Editor APIs not available in older versions.

How much does it cost?

Unity MCP is free and open source (MIT). You only pay for the AI tool you use (Claude, Codex, etc.). In-Unity Chat uses CLI tools directly — no separate API key needed.

Is my code/project data sent to the cloud?

MCP server runs locally. TCP communication is localhost-only (127.0.0.1). Your project data goes only to the AI provider you choose (Claude, Codex, etc.) through their standard API.

Can I use this with Cursor/Windsurf/VS Code?

Yes. Any MCP-compatible tool works. Setup Wizard auto-configures: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex, Kimi, OpenCode, Antigravity.

What happens during Unity domain reload?

The TCP bridge reconnects automatically. In-Unity Chat is domain-reload safe (survives recompilation). Connection recovery with exponential backoff.

Can I add my own tools?

Yes. Drop a Python file in tools/, add it to __init__.py, implement the register(mcp, send, args) pattern. Auto-discovered on server restart.

Comparison with other Unity AI tools

Feature	Unity MCP	CoplayDev	IvanMurzak	CoderGamester
MCP Tools	99	~40	70+	28
In-Editor Chat	✅ 5 backends	❌	❌	❌
Token Optimization	80-95% batch savings	❌	❌	❌
One-Liner Install	✅ curl/iex	❌	❌	❌
PlayTest DSL	✅ 21 commands	❌	❌	❌
Multi-Scene Support	✅	❌	✅	❌
AI Backends	9 (Claude, Codex, Kimi, Antigravity, OpenCode, etc.)	1	4	9
Tests	7,274	—	—	—
Code Intelligence	✅ Roslyn-powered	❌	❌	❌
Cross-Platform	✅ Win/Mac/Linux	✅	✅	✅
License	MIT	MIT	MIT	MIT

Contributing

# Python unit tests (no Unity, 2728 tests)
cd server && pytest -m "not live" -q

# Python live integration tests (Unity running on :9500, 78 tests)
pytest -m "live and not live_cli" -q

# C# EditMode tests (no play mode)
# Open Unity Test Runner → EditMode → Run All

Test Tiers:

• Tier 1 (Unit): Mocked Python (230 tests, $0) + C# EditMode (2389 tests, $0)
• Tier 2 (Integration): Python live (78 tests, $0) + NUnit PlayMode (73 tests, $0) + reload stability (39 tests, $0)
• Tier 3 (CLI): Real claude CLI with interactive I/O (4 tests, ~$0.004)

Architecture overview: AI/architecture.md · Full tool catalog: AI/mcp-server.md

_{MIT License · © German Krasnikov · ⭐ Star}