unity-biome-mcp
Summary: Control a live Unity Editor from any MCP-compatible AI client — inspect and edit scenes and components, run playtests and tests, verify results, and capture visuals.
Inspect scenes:
get_hierarchy(token-efficient trees, depth/filter/compression, incrementality),search_scene(name/type/tag/layer queries),inspect(batch multi-object component reads),get_componentwith field projection.Edit scene content:
create_object(with components/primitives/prefab instantiation),set_property(including object references, dry-run, bulkfind_type),set_active,set_parent,manage_component,delete_object, andscenemanagement (new/open/save/close/additive/save_copy).Batch operations:
batchruns many reads and writes in one call, withon_errorpolicies, atomic Undo rollback, and alias validation.Playtesting:
run_playtestexecutes a PlayTest DSL (MOVE, WAIT_UNTIL, ASSERT, INVARIANT, SIMULATE, TRACE_FLOW, CAPTURE, console-clean checks, hooks, failure snapshots);run_playtest_suiteruns multi-file suites with pass/fail matrices;lint_scene_refsvalidates scripts beforehand.Testing:
run_tests/run_tests_waitdispatch Unity EditMode/PlayMode NUnit runs with durable, idempotent run IDs and timeout-safe polling.Code authoring:
compile_preflight(Roslyn validation without recompiling),await_compile,get_compile_errors,sync_unity(Refresh/Resolve/version bump), andexecute_codefor direct in-editor C# execution.Visual verification:
screenshotsupports multiple cameras/views, zoom/angles, highlights, collider overlays, supersampling, and AI text descriptions instead of image paths.Diagnostics:
get_console/console_mark+get_console_sincefor log watermarking,mcp_status,reconnect_unity, andvalidate_referencesfor broken ObjectReferences.Guarded workflows:
scene_change_plan→apply_scene_change→verify_after_changefor pre-flight, post-verify, and optional save of scene edits.Tool discovery & efficiency:
discover_toolsenables capability categories on demand,resolve_tool_schemaloads deferred schemas, and many tools offer compression/distillation flags to save tokens.Editor control:
editorfor play/pause/stop/state/select and project path.Extensible: add project-specific server tools, Unity commands, Chat context chips, and plugin hooks; also usable via In-Unity Chat with undo-grouped AI turns.
Provides tools for inspecting and editing Unity scenes, GameObjects, components, assets, materials, shaders, and UI, as well as running playtests, capturing results, and working with animation, VFX, and batch operations.
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 | shWindows:
winget install astral-sh.uv2. Add the Unity package
In Unity, open Window > Package Manager.
Select + > Add package from git URL.
Enter:
https://github.com/german-krasnikov/unity-biome-mcp.git?path=unity-plugin3. 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 doctorSee 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 runpython install.py updateto 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 doctorThe 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 | |
Choose and configure an MCP client | |
Install project-local AI guidance | |
Find a tool for a task | |
Use batch safely | |
Build Play Mode workflows | |
Configure In-Unity Chat | |
Extend Unity Biome MCP | |
Diagnose failures |
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
Available Tools
36 toolsapply_scene_changeApply Scene ChangeB
Execute scene mutations with pre-check, post-verify, and optional save. 1.
Inputs: no named parameters.
await_compileAwait CompileARead-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 PreflightARead-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 MarkARead-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 ObjectADestructive
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 ErrorsARead-only
Compilation errors with file:line:column. Not lost on Console.Clear(). Structured, typed.
Inputs: no named parameters.
get_componentGet ComponentARead-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 ConsoleARead-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 SinceARead-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 HierarchyARead-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.
inspectInspectARead-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 RefsBRead-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 StatusBRead-only
Compact MCP status: scene, dirty, play/compile state, port, alias count.
Inputs: no named parameters.
permission_promptPermission PromptBRead-only
Handle Claude permission prompts via MCP.
Registered as --permission-prompt-tool so Claude routes all permission …
Inputs: no named parameters.
reconnect_unityReconnect UnityAIdempotent
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 TestsAIdempotent
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.
sceneSceneBDestructive
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.
screenshotScreenshotARead-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 SceneARead-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 ActiveAIdempotent
Set GameObject active/inactive.
Inputs: path (required), active (required).
set_parentSet ParentAIdempotent
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 PropertyAIdempotent
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 ReferencesARead-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
Scored across 36 tools
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.
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.
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).
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
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceSeamless 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,669Apache 2.0
- AlicenseBqualityDmaintenanceControl 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.6210 npmMIT
- FlicenseNot gradedqualityDmaintenanceA 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-
- AlicenseNot gradedqualityDmaintenanceUnity MCP Server enables LLM-based clients to automate the Unity Editor, including scene manipulation, UI testing, input simulation, and code editing.34MIT