Skip to main content
Glama

Unity Biome MCP

Control the Unity Editor from MCP-compatible AI clients or from chat inside Unity.

Inspect scenes, edit GameObjects, run playtests, and capture results through structured tools.

Quick Start

Requirements: Unity 6 (6000.0 or newer), Git 2.14+ on PATH, and uv. The MCP server does not need a separate Python installation when it runs through uvx; optional Codex skill synchronization requires Python 3.14 or newer on PATH. See the full Getting Started prerequisites.

1. Install uv

macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

winget install astral-sh.uv

2. Add the Unity package

  1. In Unity, open Window > Package Manager.

  2. Select + > Add package from git URL.

  3. Enter:

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

3. Configure your client

Open MCP > Setup Wizard, choose a client, and follow the result shown by the Wizard.

Configuration depends on the client. The Wizard may write a project configuration, run the configuration helper, copy a client-specific snippet, or defer configuration until In-Unity Chat starts. Restart the selected client when prompted. The Wizard configures the integration; it does not perform an end-to-end connection test.

Use the matching guide:

Claude Code | Claude Desktop | Codex | Cursor | Junie | Kimi | OpenCode | Rider AI Assistant | VS Code | Windsurf

For external OpenCode setup, do not use the Wizard's standard clipboard JSON: OpenCode has a different configuration shape. Follow the OpenCode guide.

4. Verify the first connection

For an external MCP client, keep the Unity project open, restart the client if the Wizard asked you to, and send:

Read the active Unity scene hierarchy at depth 2 and summarize its root objects.

The client should call:

get_hierarchy(depth=2)

A successful response contains the active scene hierarchy. If the call fails, open MCP > Status > Diagnose in Unity. For Chat-only verification, use the Chat quick check. For command-line diagnostics, run:

uvx --from git+https://github.com/german-krasnikov/unity-biome-mcp.git#subdirectory=server unity-biome-mcp doctor

See Getting Started for recovery steps and platform details.

Requirements for a source checkout: Git and Python 3.14 or newer.

Upgrading from older Python: Install Python 3.14 via brew install python@3.14 (macOS), your system package manager (Linux), or python.org (Windows). Then run python install.py update to recreate the virtual environment.

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

The configuration helper supports claude-code, claude-desktop, cursor, windsurf, vscode, codex, kimi, junie, and opencode.

Related MCP server: Unity API Communicator MCP Server

Documentation

Goal

Guide

Install and connect

Getting Started

Choose and configure an MCP client

Client guides

Install project-local AI guidance

AI Skills and Agents

Find a tool for a task

Tool Guide

Use batch safely

Batch Operations

Build Play Mode workflows

PlayTest DSL

Configure In-Unity Chat

Chat Backends

Extend Unity Biome MCP

Plugin Quick Start

Diagnose failures

Diagnostics

What You Can Do

  • Scene and object editing: inspect and modify GameObjects, components, assets, materials, shaders, and UI.

  • Playtesting and verification: run PlayTest DSL workflows, compile checks, console checks, runtime diagnostics, and visual comparisons.

  • Animation and VFX: work with clips, Animator controllers, Timeline, particles, materials, shaders, and Shader Graph.

  • Efficient tool use: group compatible operations with batch, request deferred schemas, and enable capability categories only when needed.

  • Extensibility: add project-specific server tools, Unity commands, Chat context chips, and plugin hooks.

Example prompts:

Create a player object, add a Rigidbody, and place it at the scene origin.

Find enemies without colliders and add a BoxCollider to each.

Run a playtest that moves the player to the door and verifies that the score increases.

Capture the Game View and compare it with the saved baseline.

Summarize scene changes since the last checkpoint.

Batch example

Use batch for two or more compatible operations:

batch(commands="""
create_object name=Enemy
set_property path=Enemy component=Transform prop=position value=0,1,0
manage_component path=Enemy type=Rigidbody action=add
set_property path=Enemy component=Rigidbody prop=mass value=2
""")

Some typed tools are direct-only and cannot be placed in a batch. See the Batch guide for validation, Undo-backed rollback, and error handling.

Ways to Work

External MCP client

An MCP client launches the Python server over stdio. The server discovers the active Unity project and sends framed commands to the editor plugin over localhost TCP.

In-Unity Chat

Open MCP > Chat to work inside the editor. Select a supported CLI backend and use Ask or Agent mode. Authentication is handled by the selected CLI. Context chips can attach scene objects, scripts, and assets to a turn, while each completed AI turn is grouped for Unity undo.

See Chat backends for setup and behavior.

Architecture

The external path is MCP client -> Python MCP server -> localhost TCP -> Unity Editor plugin. In-Unity Chat invokes the selected CLI through the local chat relay; that CLI connects to the same Python MCP server and rejoins the shared TCP-to-plugin path.

AI Skills

The Unity package includes 12 reusable domain skills and 4 focused agents for Claude Code and Codex. They cover efficient MCP tool selection, batching, Unity authoring, playtesting, diagnostics, and evidence-based verification.

Open MCP > Install AI Skills to install them into the current project. Existing and generated files are ownership-checked before replacement. See AI Skills and Agents for paths, safe updates, and Codex synchronization.

Project Inventory

The values below are generated from registrations, pytest collection, Unity test discovery or source scanning, and package metadata. They are discovery counts, not a claim that every test was executed in the current checkout.

Unity MCP Product Comparison

Verified August 16, 2026:

  • Unity Biome MCP: 160 registered tools, deterministic PlayTest DSL, and visual baseline/diff workflows.

  • Unity MCP Server 2.17: first-party local bridge, connection approval, and multi-client support.

  • MCP for Unity 10.1.2: Unity 2021.3 compatibility, 47 tool entrypoints, and authenticated remote hosting.

  • AI Game Developer 0.87.0: compiled-player runtime plus local, HTTP, cloud, and Docker deployment.

  • MCP Unity: 33 listed tools, optional Undo rollback for batches, and an MCP App dashboard.

The detailed matrix cites exact source commits or versioned official documentation and records constraints as well as strengths.

Open the full source-backed comparison

Recent Changes

Current release: v3.0.3 (2026-11-17). Read the full changelog.

Contributing

Read CONTRIBUTING.md before opening a pull request. New contributors can start with good first issues.

Report security issues through SECURITY.md.

License

MIT · Third-Party Notices

Available Tools

36 tools
apply_scene_changeApply Scene ChangeB

Execute scene mutations with pre-check, post-verify, and optional save. 1.

Inputs: no named parameters.

await_compileAwait CompileA
Read-only

Block until Unity finishes compiling + reloading, then return compile errors. Use after writing .cs files instead of sleep. Returns errors or 'compile clean (Xs)'. Handles domain reload disconnects transparently. timeout=0 → immediate check, no loop. Epoch-aware via sync_status when available (+10 from MAJOR-1); falls back to compile_status.

Inputs: timeout.

batchBatchA

Execute multiple commands in one call. Use for 2+ ops — reads AND writes. commands: one per line (cmd key=value). on_error: continue|stop (default continue). timeout: seconds (default 75). atomic: True reverts ALL prior ops on first failure (Unity Undo); execute_code fs side-effects NOT reverted. PREFER over individual tool calls.

Inputs: commands (required), atomic, timeout, on_error, +1 more.

compile_preflightCompile PreflightA
Read-only

Validate C# WITHOUT writing/recompiling (Roslyn). Use before writing .cs — catches typos in ~200ms vs 30s recompile. file_path: Assets-relative. new_content: full file. Returns OK preflight (ms) / ERR preflight + diagnostics / [ROSLYN UNAVAILABLE].

Inputs: file_path (required), new_content (required).

console_markConsole MarkA
Read-only

Create a console watermark. Returns mark_id encoding current timestamp. Pass to get_console_since() to retrieve only logs after this point. Pure Python — no TCP call.

Inputs: label.

create_objectCreate ObjectA

Create new GameObject. components: comma-separated types to add on creation. primitive: Cube|Sphere|Cylinder|Capsule|Plane|Quad. prefab_path: instantiate from prefab asset. scene: create in named loaded scene (omit = active scene).

Inputs: name (required), scene, parent, primitive, +2 more.

delete_objectDelete ObjectA
Destructive

Delete GameObject by instance ID or scene path.

Inputs: no named parameters.

discover_toolsDiscover ToolsA

Find and enable tools by category. Canonical 8: SCENE, COMPONENTS, ASSETS, MEDIA, VERIFY, RUNTIME, TESTS, SYSTEM. include_legacy=True adds legacy aliases (object, animation, etc.). structured=True adds surface/mutability info. enable=False to browse only.

Inputs: enable, category, structured, include_legacy.

editorEditorB

Editor state/control. action: state|play|pause|stop|select|project_path. select: path (single) or paths (comma-sep multi, e.g. "/Player,/Enemy,/NPC").

Inputs: path, paths, action.

execute_codeExecute CodeA

Execute C# code in Unity Editor via Roslyn. 10-40x faster than recompile. Security: no System.IO, System.Net, System.Diagnostics. Bare statements are auto-wrapped in a static class — no boilerplate needed. Example: "var go = new GameObject("Test"); return go.name;"

Inputs: code (required), undo_label.

get_compile_errorsGet Compile ErrorsA
Read-only

Compilation errors with file:line:column. Not lost on Console.Clear(). Structured, typed.

Inputs: no named parameters.

get_componentGet ComponentA
Read-only

Component properties as key-value. For MULTIPLE objects, use inspect(paths='a,b,c') instead — 1 call vs N. fields: comma-separated field names to keep (e.g. 'mass,position') — projects the result to save tokens; shows requested fields even at default values. Aliases: position, rotation, scale, mass, enabled, active, name. full=True: bypass distillation, return raw response. compress=True: strip default values before transfer.

Inputs: path (required), type (required), full, fields, +1 more.

get_consoleGet ConsoleA
Read-only

Recent console logs. For C# compile errors use get_compile_errors instead. keyword: case-insensitive substring filter. count_only: return N matches as string. since: only logs from last N seconds.

Inputs: count, first, level, since, +2 more.

get_console_sinceGet Console SinceA
Read-only

Console entries after the watermark created by console_mark(). mark_id: string from console_mark() or bare float timestamp. level: optional filter ('error,exception,assert'). keyword: case-insensitive substring filter. count_only: return match count as string. count: max entries to return (default 500).

Inputs: mark_id (required), count, level, keyword, +1 more.

get_hierarchyGet HierarchyA
Read-only

Scene hierarchy as text tree. For finding specific object by name/type use search_scene. Max 3000 nodes. Use filter/depth to narrow. Set components=true to see component types. Set compress=true to group repeated slots/points/meshes. Set summary=true for compact root-only counts (60-100 tokens). Set incremental=true to get NO_CHANGE if scene unchanged since last call. full=True: bypass distillation. scene: filter to a single scene by name (multi-scene only).

Inputs: full, root, depth, scene, +5 more.

inspectInspectA
Read-only

Get components for multiple objects at once. paths: comma-separated. components: comma-separated types (default: all). find_type: component type to find — populates paths automatically (replaces explicit paths). fields: comma-separated field names to keep across all objects — projects the result to save tokens. full=True: bypass distillation. compress=True: strip default values before transfer.

Inputs: full, paths, fields, compress, +2 more.

lint_scene_refsLint Scene RefsB
Read-only

Read-only linter for scene references in DSL scripts or batch commands. path: project-relative path to .playtest fil…

Inputs: no named parameters.

manage_componentManage ComponentA

Add or remove a component. Mutates scene. No confirmation required. action: 'add' or 'remove' ONLY (no 'enable'/'disable' — use set_property with prop='m_Enabled' for that). type: short name (e.g. 'Button') or full namespace (e.g. 'UnityEngine.UI.Button').

Inputs: path (required), type (required), action (required).

mcp_statusMcp StatusB
Read-only

Compact MCP status: scene, dirty, play/compile state, port, alias count.

Inputs: no named parameters.

permission_promptPermission PromptB
Read-only

Handle Claude permission prompts via MCP.

Registered as --permission-prompt-tool so Claude routes all permission …

Inputs: no named parameters.

reconnect_unityReconnect UnityA
Idempotent

Reconnect to Unity. Port 0 or omitted = auto-discover from port files.

Inputs: no named parameters.

resolve_tool_schemaResolve Tool SchemaB

Return full parameter schemas for deferred tools. tools=comma-separated names.

Inputs: tools (required).

run_playtestRun PlaytestA

[Play Mode] Execute a playtest DSL script. Returns structured report (for NUnit tests, use run_tests). Commands: MOVE TO x,y,z | WAIT n | WAIT_UNTIL query op value | ASSERT query op value | ASSERT_CONSOLE_CLEAN [IGNORE "pat"] | SNAPSHOT queries | INVOKE path comp method args | SET path comp field value | LOG msg | TIMESCALE n | ASSERT_CONSERVED SUM a+b OVER t | ASSERT_CTA VISIBLE|CLICKABLE | VAL name query | TELEPORT path x,y,z | ASSERT_BATCH...END | ASSERT_NEAR pathA pathB dist | INVARIANT query op value | SIMULATE name [DURATION n] [TIMESCALE n] | MONITOR name | TRACE_FLOW FROM a TO b FIELD f | CAPTURE label query | ASSERT_CAPTURED label INCREASED|DECREASED. defs: inline VAL definitions prepended to script.

Inputs: defs, path, fresh, script, +5 more.

run_playtest_suiteRun Playtest SuiteA

[Play Mode] Run multiple .playtest files sequentially and return a compact matrix. Enters Play Mode. No confirmation required. pattern: glob pattern (e.g. 'Playtests/*.playtest'), comma-separated list, or newline-separated list of project-relative paths. suite_path: absolute path to a .suite file (lines = project-relative .playtest paths, # = comment). Exactly one of pattern or suite_path must be provided. stop_on_fail=True: abort suite after first failure. stop_after=True: exit Play Mode when suite completes. auto_play=True: enter Play Mode automatically if not already playing. restart_between=True: stop+play between each file to reset runtime state. Output: SUITE: X/Y passed (Zs) + per-file line + full failure details.

Inputs: pattern, auto_play, stop_after, suite_path, +3 more.

run_testsRun TestsA
Idempotent

Dispatch Unity tests and return their durable identity immediately.

A successful response is
``tests-started|request_id=...|run_id=...|utf_guid=...|state=dispatched``.
If transport fails after dispatch may have happened, the result is
``START-UNKNOWN`` with the same request_id; resolve it instead of retrying
with a new identity.

Inputs: mode, filter, request_id.

run_tests_waitRun Tests WaitA

Dispatch tests and wait for the exact run to become terminal. Dispatches test run. No confirmation required.

Transport failures and domain reloads do not erase the last snapshot. A
caller timeout is observational only: it returns ``TIMEOUT`` with request,
run and snapshot data and never marks the Unity run complete.

Inputs: mode, filter, timeout, request_id, +1 more.

sceneSceneB
Destructive

Scene management. action: new|open|save|discard|open_additive|close|set_active|list|save_copy. path: required for open/save/open_additive/close/set_active/save_copy. list requires no path. scene: save/discard/save_copy target when multiple scenes loaded (identifies by name). save_copy: writes current dirty state to path as backup; active scene reference unchanged. include_unsaved: always True — save_copy always captures current in-memory state.

Inputs: action (required), path, scene, include_unsaved.

scene_change_planScene Change PlanC

Pre-flight + plan for safe scene edit. 1.

Inputs: no named parameters.

screenshotScreenshotA
Read-only

Capture screenshot (file path); describe= -> Haiku text (15-100x fewer tokens), raw=True forces path. camera: scene_view|scene_view_frame|multi_view|single_view|overview|overview_game. angle (single_view): front|left|top|iso|ex,ey,ez. zoom: higher=closer. angles: per-view Euler "ex,ey,ez|..." (_=skip). supersample 1-4. offset/fixed_size: framing. highlight: paths[:#RRGGBB] for bbox. show_colliders: wireframes. annotation_id: frame + highlight annotation by id (auto sets camera=annotation_frame).

Inputs: raw, path, zoom, angle, +12 more.

search_sceneSearch SceneA
Read-only

Search scene objects. Syntax: name text, t:Component, tag=Tag, layer=N, active=bool. Combine with spaces. root: scope search to subtree (path or None for whole scene). limit: max results (default 50; 0=unlimited). scene: filter to a single scene by name (multi-scene only).

Inputs: query (required), root, limit, scene.

set_activeSet ActiveA
Idempotent

Set GameObject active/inactive.

Inputs: path (required), active (required).

set_parentSet ParentA
Idempotent

Reparent existing GameObject. parent=null → move to scene root. world_position_stays=True (default): preserves world transform. False: stays local to new parent.

Inputs: path (required), parent, world_position_stays.

set_propertySet PropertyA
Idempotent

Set component property (Edit Mode, SerializedObject — for Play Mode use invoke_method or execute_code). find_type: component type — bulk-sets prop on all matching objects without specifying paths. For GO rename use rename_object(). ObjectReference: scene path (/Player), asset path (Assets/X.mat), sub-asset (Assets/X.fbx::ClipName), $hexId (e.g. $3E8) or #instanceID (legacy), or 'null'. dry_run=True shows what would change without applying. ref_component_type: when value is a plain scene path and the field expects a specific Component type (e.g. 'BoxCollider'), appends '::TypeName' to the value so C# resolves the correct component. Ignored when value already contains '::'.

Inputs: path, prop, value, dry_run, +3 more.

sync_unitySync UnityA

Unified Unity reload: trigger Refresh (+ optional Resolve), wait for new code to live.

resolve=True: call Client.Resolve() first (use after package.json change).
bump=True: atomically increment plugin patch version BEFORE sync, implies resolve=True.
Returns: 'sync clean' / compile errors / timeout message.

Inputs: bump, resolve, timeout.

validate_referencesValidate ReferencesA
Read-only

Validate all ObjectReference fields under path recursively. Returns [ERROR]/[MISSING] for broken refs. Summary: "N ERROR, M OK". Use depth=1 for quick top-level scan, depth=3-5 for full subtree. verbose=True also shows [OK] lines (off by default to save tokens). ignore_optional=True skips fields marked [Optional] (reduces noise).

Inputs: path (required), depth, verbose, ignore_optional.

verify_after_changeVerify After ChangeC

Single verification gate after code/scene changes. Gates are additive — only enabled ones run: 1.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 36 tools

    Disambiguation5/5

    Each tool targets a distinct resource and operation, with clear separation between similar tools like get_component vs inspect (single vs multi-object) and compile_preflight vs await_compile (pre-write validation vs post-write wait). No two tools appear to overlap.

    Naming Consistency4/5

    The dominant pattern is verb_noun snake_case (get_hierarchy, create_object, run_tests), with a few noun-only tools (scene, editor, batch) that function as grouped action commands. The inconsistency is minor but prevents a perfect score.

    Tool Count2/5

    With 36 tools, this exceeds the 25-tool threshold for 'too many' per the rubric. While the domain is complex, the server could reduce surface area by consolidating related operations (e.g., console_mark+get_console_since, scene_change_plan+apply_scene_change).

    Completeness4/5

    The set covers scene hierarchy creation/deletion/editing, component inspection/modification, play mode testing, test dispatch, compilation, console logging, screenshots, and editor state. Minor gaps exist (e.g., no duplicate object, no asset creation beyond prefabs) but execute_code provides a general escape hatch.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Seamless automation and intelligent control over your Unity projects. By integrating with the MCP server and client, it allows AI agents or external tools to interact with your Unity environment—creating, modifying, and managing GameObjects, Components, Assets, Scenes, and more.
      4,669
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      Control Unity Editor from AI agents. 200+ MCP tools for GameObjects, Scenes, Assets, Materials, Prefabs, Terrain, Physics, Lighting, and more. Works with Claude, Cursor, Windsurf, VS Code Copilot — any MCP client. Zero config: just npx and go.
      62
      10 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A native C# MCP server that gives AI agents real-time control and visual analysis of the Unity Editor, enabling dynamic code execution, scene manipulation, and debugging without external dependencies.
      8
      -