Unity Semantic Bridge

A Unity MCP Bridge built for agents working alongside you in a live Editor session — not just querying a static project. Token-efficient tools give your agent visibility into what changed in the scene while you were both working in it.

Features

• Optimized scene heirarchy query and gameobject inspection tools with workflow hints for agents - more token efficient than official Unity CLI tool
• In Editor connection status and reconnect. Not tied to Unity Licensing - Runs 100% local. No need to reauthenticate when token expires
• Dedicated tools for agent to see human actions and changes
• In Editor MCP log so you can see what tools are called
• Dedicated Lighting tools for URP projects

Prerequesites

• Unity 2022.3 LTS up to Unity 6.3
  • uses UnityEditor.ObjectChangeEvents.changesPublished available in 2022.3 LTS and later
  • versions of Unity newer than 6.3 use change InstanceIds for EntityIds - not tested for compatibility yet
• uv (https://docs.astral.sh/uv/getting-started/installation/)

Optional

• API key for LLM with strong vision capabiltiies - lighting subagent can be powered by a separate LLM (ideally with vision-in-the-loop like Fable 5 or Kimi K3); see /core/llm_provider.py. Tools are still available to your main/orchestrator agent even without setting up the subagent. Previously used mcp sampling but this was deprecated.

Installation

1. Clone this project.
2. Add the Unity package in /com.gamenami.unity-semantic-bridge to your Unity project via "add package from disk".
3. You should have uv installed so it can run and automatically update the server's dependencies. Add the MCP Server in /mcp-editor-bridge to your preferred IDE Agent's list of MCP servers. The MCP server POSTs to the Unity Editor's HTTP listener at http://127.0.0.1:1073/mcp.

"mcpServers": {
    "unity-semantic-bridge": {
		"command": "uv",
		"args": [
			"--directory", "<YOUR_LOCAL_PATH_TO_/unity-semantic-bridge/mcp-editor-bridge>",
			"run", "main.py"
		]
    }
}

4. In Unity, from the Tools menu, select "Unity Semantic Bridge" > "Start HTTP Listener" (port 1073). Your IDE Agent now has access to your Unity Project and MCP tools provided. Health check: GET http://127.0.0.1:1073/health.

Available Tools

Human-Agent Cowork

• get_recent_unity_events — Returns Unity Editor events (hierarchy/selection/play-mode/console/objectChanged via ObjectChangeEvents.changesPublished) pushed since a time window — use to see human edits, add_component/remove_component/set_field_values etc.
• notify_unity — Sends a message to the Unity Editor chat window (BridgeRelay.OnAgentMessage).

Project & Settings

• get_project_settings — Returns Unity Project Settings as JSON. Selectively fetch core (Unity version, build target), rendering (URP asset, color space, MSAA), input (Input Handling, inputactions assets), ui (uGUI vs UI Toolkit counts), scripting (API level, define symbols, backend), tags_layers.

Scene & GameObject Inspection

• get_scene_hierarchy — Returns the scene as a list of GameObjects with paths and instance IDs. Usually the first tool to call. Supports depth limiting, a node cap with truncation reporting (for large scenes), optional filtering to only main-camera-visible objects, and root_instance_id subtree queries.
• get_gameobject_tree — Full hierarchy under a specific GameObject (faster than get_scene_hierarchy for rigs; avoids SkinnedMeshRenderer pruning).
• inspect_gameobject — Detailed inspection of a GameObject including components and public fields (uses ComponentInspector with expanded Generic structs).
• get_component_inspector_values — All serialized field values visible in the Inspector for a specific component (live Editor values, expands RigBuilder/Rig/*Constraint.m_Data/Transform.m_LocalRotation as structured quat+euler).
• get_component_code — Locates and returns the full C# source for a named component (MonoScript via AssetDatabase).
• get_unity_physics_layers — Physics layer collision matrix (Physics.GetIgnoreLayerCollision).

Scene & GameObject Authoring (Hierarchy & Rigging)

• create_gameobject — Creates a new GameObject (new GameObject(name)) with Undo.RegisterCreatedObjectUndo, optional parentInstanceId via SetParent(parent,false), and optional localPosition/localRotation ({x,y,z,w} or {euler}) / localScale. Returns {instanceId,path}.
• duplicate_gameobject — Duplicates a hierarchy via Instantiate + Undo.RegisterCreatedObjectUndo (use for cloning whole rig layers, e.g. Rig Layer (Rifle Idle)). Returns {instanceId,path}.
• set_parent — Reparents via Undo.SetTransformParent (or RegisterCompleteObjectUndo+SetParent when keepWorldPosition:true). Pass null to unparent to root.
• delete_gameobject — Deletes a GameObject via Undo.DestroyObjectImmediate (supports Undo).
• copy_component — Deep-copies a component via Undo.AddComponent + EditorUtility.CopySerialized (required for Animation Rigging Constraint.data structs where m_Data: [Generic] cannot be rebuilt via set_field_values). Returns {targetComponentIndex,targetInstanceId}.
• add_component — Adds a component by instance_id (Type.GetType + assembly fallback, respects allowDuplicate).
• remove_component — Removes a component by instance_id (Undo.DestroyObjectImmediate).
• set_field_values — Sets one or more serialized field values via SerializedObject/FindProperty + Undo.RecordObject (supports primitives, enums as strings, Vector2/3, Quaternion, Color, ObjectReference as instanceId, Generic/Array for RigBuilder/Constraint data).

Assets & ScriptableObjects

• find_unity_files — Finds assets in Unity via AssetDatabase.FindAssets (t:Prefab, l:Label, etc.), default folders:['Assets'].
• find_asset_references — Finds assets/scenes referencing a specific asset path (AssetDatabase.GetDependencies).
• get_project_tree — Project folder structure from a path (AssetDatabase.GetSubFolders + direct-file filter).
• write_unity_script — Creates/overwrites a C# script (Assets/...cs) and triggers recompilation (AssetDatabase.ImportAsset/Refresh, CONFIRM_REQUIRED pattern).
• create_scriptable_object — Creates a ScriptableObject asset atomically without write_unity_script: Type.GetType + assembly fallback, ScriptableObject.CreateInstance, field init via SerializedObject (primitives, enums as "cross"→UnitId.cross, Vector3 {x,y,z}, Object refs as instanceId/guid/{fileID,guid}), Undo.RegisterCreatedObjectUndo + AssetDatabase.CreateAsset/SaveAssets/Refresh. Validates Assets/ + .asset, parent folder exists, ScriptableObject subclass, CONFIRM_REQUIRED on overwrite. Returns {instanceId,guid,path}.
• delete_asset — Deletes an asset via AssetDatabase.DeleteAsset (supports Undo, validates Assets/).
• get_compilation_status — Non-blocking snapshot of compilation (PENDING/SUCCESS/FAILED with errors) — poll after write_unity_script.

Editor & Runtime

• get_screenshot — Captures game (Camera.main) or scene (Scene view) as JPEG; scene can Frame a focus_instance_id bounds before capture.
• set_unity_play_mode — Enters/exits Play Mode (EditorApplication.isPlaying via delayCall).
• get_unity_console_logs / clear_unity_console_logs — Read last 10 errors/warnings via LogEntries reflection or clear (LogEntries.Clear).

Lighting Diagnostics

• get_lights_affecting_object — Lights within range of a target object using actual bounds distance, per-light type/intensity/range/cullingMask (uses GetLightsAffectingObject).
• get_urp_pipeline_settings — URP asset’s current render path setting (GetUrpPipelineSettings).
• diagnose_lighting_issue — Autonomous diagnostic subagent (lights → URP → renderer/materials) via core.llm_provider; see LightingAgent/README.md. Requires LIGHTING_LLM_PROVIDER/MODEL + API key.

Known Limitations (for Agents using this tool to read)

• Unity instance IDs are not stable across script recompiles or domain reloads. Any C# change invalidates previously-fetched instance IDs — re-run get_scene_hierarchy after recompiling before reusing an ID from an earlier call.
• The Editor connection is single-flight. Only one MCP request is processed at a time; overlapping calls queue rather than run concurrently, since Unity's Editor-side message handling is inherently serial.