Unity Semantic Bridge MCP server
Commit 26 Okt 2026Memungkinkan AI agent untuk berinteraksi dengan sesi Unity Editor secara live untuk manipulasi scene secara real-time, inspeksi hierarchy, dan authoring uGUI.
Juga dikenal sebagai Programalyst/unity-semantic-bridge
- Stars
- 8
- Tools
- 39
- Unduhan, 30 hari
- —
- Versi terbaru
- —
- Commit terakhir
- 26 Okt 2026
- Lisensi
- Apache-2.0
Apa itu Unity Semantic Bridge MCP?
Unity Semantic Bridge adalah MCP server. Memungkinkan AI agent untuk berinteraksi dengan sesi Unity Editor secara live untuk manipulasi scene secara real-time, inspeksi hierarchy, dan authoring uGUI. Server ini menyediakan 39 tool, seperti get_recent_unity_events, get_project_settings, get_scene_hierarchy.
Ringkasan dibuat dari README proyek
Tentang Unity Semantic Bridge MCP server
Unity Semantic Bridge menyediakan koneksi khusus antara AI agent dan sesi Unity Editor yang sedang berjalan. Berbeda dengan tools yang hanya melakukan query pada file proyek statis, server ini memungkinkan agent untuk mengamati perubahan real-time yang dilakukan oleh manusia dan berinteraksi langsung dengan scene yang aktif. Tool ini dirancang untuk developer yang mengerjakan proyek URP dan uGUI, menawarkan visibilitas tinggi terhadap scene hierarchy, nilai component inspector, dan event editor terbaru.
Untuk menggunakan bridge ini, Anda harus menginstal package Unity dan menjalankan Python MCP server secara lokal menggunakan uv. Setup ini memerlukan koneksi client Python ke Unity HTTP listener melalui port tertentu, yang dapat dikonfigurasi untuk mendukung beberapa proyek editor secara bersamaan. Server beroperasi sepenuhnya secara lokal tanpa memerlukan lisensi Unity atau API key eksternal untuk fungsi utamanya. Ini mencakup tools khusus untuk batch property edits, perbandingan prefab, dan tugas authoring uGUI yang kompleks, memastikan bahwa tindakan agent terintegrasi ke dalam sistem undo editor.
Apa yang bisa Anda lakukan dengannya
- 1Monitor perubahan editor manusiaSeorang agent dapat melacak apa yang telah dimodifikasi oleh developer di dalam scene agar tetap sinkron.
- 2Automasi pembuatan UIDeveloper dapat menginstruksikan agent untuk membangun dan mengatur layout seluruh hierarchy user interface.
- 3Melakukan batch property updatesSeorang agent dapat mengubah banyak nilai component sekaligus dengan safety checks dan dukungan undo.
- 4Inspeksi character rig yang kompleksSeorang agent dapat menelusuri skeleton karakter untuk memahami strukturnya.
Ditulis berdasarkan README proyek. Setiap use case diperiksa terhadap kutipan dari README tersebut.
Tool Unity Semantic Bridge MCP 39
Terdeteksi dari READMEget_recent_unity_eventsget_project_settingsget_scene_hierarchyinspect_gameobjectacquire_editor_referencessemantic_batchcreate_gameobjectduplicate_gameobjectset_parentdelete_gameobjectcopy_componentadd_component
| get_recent_unity_events | — | |
| get_project_settings | — | |
| get_scene_hierarchy | — | |
| inspect_gameobject | — | |
| acquire_editor_references | — | |
| semantic_batch | — | |
| create_gameobject | — | |
| duplicate_gameobject | — | |
| set_parent | — | |
| delete_gameobject | — | |
| copy_component | — | |
| add_component | — |
Tampilkan semua 39 toolTampilkan lebih sedikit tool
remove_componentset_field_valuesauthor_uifind_unity_filesinspect_prefab_assetsinspect_model_assetbake_layoutcreate_layout_scenevalidate_layoutapply_layoutrender_layout_topdownquery_level_cataloggenerate_asset_catalogfind_asset_referenceswrite_unity_scriptcreate_scriptable_objectdelete_assetrefresh_assetsget_compilation_statusget_screenshotopen_scenepoll_play_stateinvoke_menu_iteminvoke_staticset_editor_throttlingget_console_logsget_lights_affecting_object
| remove_component | — | |
| set_field_values | — | |
| author_ui | — | |
| find_unity_files | — | |
| inspect_prefab_assets | — | |
| inspect_model_asset | — | |
| bake_layout | — | |
| create_layout_scene | — | |
| validate_layout | — | |
| apply_layout | — | |
| render_layout_topdown | — | |
| query_level_catalog | — | |
| generate_asset_catalog | — | |
| find_asset_references | — | |
| write_unity_script | — | |
| create_scriptable_object | — | |
| delete_asset | — | |
| refresh_assets | — | |
| get_compilation_status | — | |
| get_screenshot | — | |
| open_scene | — | |
| poll_play_state | — | |
| invoke_menu_item | — | |
| invoke_static | — | |
| set_editor_throttling | — | |
| get_console_logs | — | |
| get_lights_affecting_object | — |
Pengecekan otomatis
Berjalan 15 Nov 2026Laporan lengkap →Belum diverifikasi. Sebuah server memerlukan skor 80, tidak ada temuan serius, dan data yang cukup untuk kami periksa. Cara kerja checks · Yang perlu diperbaiki untuk menambah poin
- Source repository terhubung dan dapat dijangkauprogramalyst/unity-semantic-bridge is public and reachablegithub.com/programalyst/unity-semantic-bridge ↗Lolos
- Nama paket mencantumkan repositori ini sebagai sumbernyaTidak diperiksa
- Provenance build (atestasi Sigstore)Tidak diperiksa
- Lisensi open source (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Lolos
- Ada commit atau release dalam satu tahun terakhirLast commit or release 2026-10-26github.com/programalyst/unity-semantic-bridge ↗Lolos
- OpenSSF ScorecardTidak diperiksa
- Nama package tidak mirip dengan package populerTidak diperiksa
- Tidak ada advisory kritis pada paket atau dependensinyaTidak diperiksa
- Tidak ada instruksi tersembunyi untuk model39 tool descriptions and the README read; no override phrases, credential paths or hidden charactersLolos
- Tools yang bersifat destruktif telah diberi labelTidak diperiksa
- Endpoint remote merespons handshake MCPTidak diperiksa
README
Lihat di GitHubUnity Semantic Bridge (USB)
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.
Note: Unity Semantic Bridge is optimized for projects that use uGUI and URP (Universal Render Pipeline). If your project uses UI Toolkit, HDRP or BiRP use the official Unity CLI instead
What's New
October 17, 2026: Tool cleanup
- Removed
notify_unityandset_play_mode. Useenter_play/exit_play, which wait for the transition to finish and survive domain reloads. - Merged
get_gameobject_treeintoget_scene_hierarchy. To walk a character's skeleton, pass the character asroot_instance_idwithprune_skinned=Falseand a deepdepth. Rooted queries also now honourdepthbelow the root; before, they returned only the root node. - Merged
get_component_inspector_valuesintoinspect_gameobject. Passcomponentto read one component's Inspector values, or omit it to read every component. - Removed
get_urp_pipeline_settings. Its data is inget_project_settings(sections=["rendering"]). - Removed
diagnose_lighting_issueand its LightingAgent subagent, so no tool needs an LLM API key any more. Agents run the diagnosis themselves:get_lights_affecting_objectnow describes the steps (lights in range, URP rendering path and light limits, renderer settings, screenshot). - Merged
clear_console_logsintoget_console_logs(clear=True), which clears after reading. - Merged
get_physics_layersintoget_project_settings(sections=["physics"]), which returns the collision matrix as JSON: each layer and the layers it collides with. - Removed
get_component_codeandget_project_tree. Agents grep and list files directly. The server instructions now say where Unity package sources live on disk, includingLibrary/PackageCache/for git and registry packages, which needsrg --no-ignore.
October 15, 2026: Multi-Editor support
- Several Unity Editors at once. Each project now has its own bridge ports (defaults 1073/1074), set in Tools > Unity Semantic Bridge and stored per user in
UserSettings/. Register the same MCP server once per project under different names (for exampleunity-semantic-bridgeandunity-ap), each with matching--unity-port/--event-port, for example a game project on 1073/1074 and an asset-library project on 1075/1076. See several Unity projects at once. - Several agent sessions on one Editor. Every MCP server attached to an Editor now receives its events, so
get_recent_unity_eventsworks in each agent session, not only the first. See several agent sessions on one Editor. - The listener's auto-start after domain reloads is now per Editor,
GET /healthreports which project answers, and connection errors name the URL and ports to check. - Background refreshes.
refresh_assetsnow completes in an Editor that is hidden or behind other windows: refresh, compile and domain reload finished in 11 seconds in a hidden Editor, which previously waited until you clicked back into Unity.
Showcase
Made with USB:
Battle Stations Next - 3D Modernization of a classic Facebook Flash game from 2008. Playable demo on Unity Play here
Nuclear Knights - Turn based tactics in a Wasteland like setting
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 auto reconnect through domain reloads.
- 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
- Dedicated tools for working with Scriptable objects (error prone if agent uses bash to work SOs directly)
- Dedicated tools for uGUI. Makes uGUI accessible for agents to create a hierarchy, set layout properties, assign references, and inspect the result
- Bounded batch inspection and property edits with dry runs, expected-value checks, stale-reference protection, and grouped Undo
- Read-only prefab comparisons with component filtering and structured numeric values that preserve imported precision
- In Editor MCP log so you can see what tools are called
- Dedicated Lighting tools for URP projects
Prerequisites
Installation
Install both the Unity package and the Python MCP server:
-
In Unity, open Window > Package Manager > + > Add package from Git URL and paste:
https://github.com/Programalyst/unity-semantic-bridge.git?path=/com.gamenami.unity-semantic-bridge -
Clone the matching Python server and install its dependencies:
git clone https://github.com/Programalyst/unity-semantic-bridge.git uv --directory unity-semantic-bridge/mcp-editor-bridge sync --locked -
Register the server with your MCP client. For Codex, replace the path below with your clone's absolute path:
codex mcp add unity-semantic-bridge -- uv --directory "/absolute/path/to/unity-semantic-bridge/mcp-editor-bridge" run main.py -
In Unity, open Tools > Unity Semantic Bridge > Start HTTP Listener, then start or reconnect your MCP client. The client launches Python over stdio; Python connects to Unity on port 1073 by default. To run the bridge in several Editors at once, give each project its own ports; see several Unity projects at once.
Commit both Packages/manifest.json and Packages/packages-lock.json to share
the installation. Keep your MCP client's local clone path out of shared settings.
For upgrades, local-to-Git migration, or bridge development using Add package from disk, see the installation reference. Do not commit personal absolute package paths.
Available Tools
Human-Agent Cowork
get_recent_unity_events— Returns Unity Editor events (hierarchy/selection/play-mode/console/objectChangedviaObjectChangeEvents.changesPublished) pushed since a time window — use to see human edits,add_component/remove_component/set_field_valuesetc.
Project & Settings
get_project_settings— Returns Unity Project Settings as JSON. Selectively fetchcore(Unity version, build target),rendering(URP asset, color space, MSAA),input(Input Handling,inputactionsassets),ui(uGUI vs UI Toolkit counts),scripting(API level, define symbols, backend),tags_layers,physics(layer collision matrix). Theeditor_prefssection reports the current Interaction Mode, stored idle time, and restore availability; these are user-level Editor preferences.
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, androot_instance_idsubtree queries. Objects with aSkinnedMeshRendererare skipped by default; passroot_instance_idwithprune_skinned=Falseand a deepdepthto walk a character's rig.inspect_gameobject— Serialized field values visible in the Inspector for every component on a GameObject, or only the one named bycomponent(live Editor values viaComponentInspector; expandsRigBuilder/Rig/*Constraint.m_Data/Transform.m_LocalRotationas structuredquat+euler).
Batch Inspection & Property Edits
acquire_editor_references— Converts 1–64 live GameObject/component instance IDs into opaque references forsemantic_batch. Verify the returned identities before editing; reacquire references after reloads, scene/Prefab Stage changes, deletion, or cache eviction. Asset IDs are rejected.semantic_batch— Runs 1–64 ordered operations with unique IDs: either allinspector allset_fields. Inspections return structured properties or component identities and continue after individual errors. Edits supportdry_run, exact expected-value preconditions, whole-request preflight, execution-time revalidation, and one named Undo group within one editable scene/Prefab Stage (Auto Save off). Execution stops on the first failure and reports skipped operations; partial application is possible and Undo grouping is not atomic. Optionallimitsbound work and response size with explicit truncation. No implicit saves or automatic mutation retries.- Usage, limits, failure semantics, and measured request savings.
Scene & GameObject Authoring (Hierarchy & Rigging)
create_gameobject— Creates a newGameObject(new GameObject(name)) withUndo.RegisterCreatedObjectUndo, optionalparentInstanceIdviaSetParent(parent,false), and optionallocalPosition/localRotation({x,y,z,w}or{euler}) /localScale. Returns{instanceId,path}.duplicate_gameobject— Duplicates a hierarchy viaInstantiate+Undo.RegisterCreatedObjectUndo(use for cloning whole rig layers, e.g.Rig Layer (Rifle Idle)). Returns{instanceId,path}.set_parent— Reparents viaUndo.SetTransformParent(orRegisterCompleteObjectUndo+SetParentwhenkeepWorldPosition:true). Passnullto unparent to root.delete_gameobject— Deletes aGameObjectviaUndo.DestroyObjectImmediate(supports Undo).copy_component— Deep-copies a component viaUndo.AddComponent+EditorUtility.CopySerialized(required for Animation RiggingConstraint.datastructs wherem_Data: [Generic]cannot be rebuilt viaset_field_values). Returns{targetComponentIndex,targetInstanceId}.add_component— Adds a component byinstance_id(Type.GetType+ assembly fallback, respectsallowDuplicate).remove_component— Removes a component byinstance_id(Undo.DestroyObjectImmediate).set_field_values— Sets one or more serialized field values viaSerializedObject/FindProperty+Undo.RecordObject(supports primitives, enums as strings,Vector2/3,Quaternion,Color,ObjectReferenceasinstanceId,Generic/ArrayforRigBuilder/Constraintdata).
uGUI Authoring & Diagnostics
author_ui— Create, lay out and wire Canvas/Image/Button/TMP hierarchies in one undoable batch.inspect_ui/raycast_ui— Inspect layout, visibility and actual input hits, including camera-mask-hidden UI.undo_ui_batch/save_ui_context— Undo a batch or explicitly save its scene/prefab.- Usage and examples.
Assets & ScriptableObjects
find_unity_files— Finds assets in Unity viaAssetDatabase.FindAssets(t:Prefab,l:Label, etc.), defaultfolders:['Assets'].inspect_prefab_assets— Reads selected serialized property paths from matching components throughout 1–32 imported prefab assets underAssets/orPackages/. Resolves variants, nested prefabs, and inactive objects; returns sibling-indexed hierarchy paths, component identities/indices, and typed numeric values without display rounding. Optionallimitsbound traversal, expansion, response size, and cooperative execution time, with explicit truncation. Reads imported asset values rather than unsaved Editor overrides, without instantiating, selecting, modifying, reimporting, or saving assets/scenes.inspect_model_asset— Inspects an imported FBX/OBJ or otherModelImporterasset by path. Reports mesh IDs, bounds, geometry counts, imported hierarchy/transforms, importer scale/axis settings, material slots, and outgoing dependencies.include_details=Trueadds submesh and importer details. Read-only; see coordinate definitions and examples.bake_layout— Reads a scene (the active one, or an open one byscenepath) back into compact grid-layout JSON ({"v":1,"size":[w,h],"pieces":[[localId, prefabGuid, x, y, rot]],"deploy":[[x,y]],"enemies":[...],"decor":[]}) through the game'sIGridRulesAdapter(Runtime/Layout/). Off-grid rotation, scale or position, off-board and non-prefab blockers are reported, never snapped; also lists cells where the layout disagrees with the game's own occupancy bake. Optionalpathwrites the JSON underAssets/. Edit Mode only. See grid layouts for the format, the USB/game split and a flow diagram.create_layout_scene— A new level from a template level scene: copies the scene and its level asset, repoints the copy to the new level, clears the template's generated layout and sets the board size. Saves both; never opens scenes or edits Build Settings.get_layout/set_layout— Read a layout file (summary plus canonical JSON), or schema-check and write one (prefab paths may stand for GUIDs; nothing is written on a schema error; the grid-tier report follows).validate_layout— Cell-addressed report for a draft (tier="grid", no scene touched) or an open scene against the game's occupancy bake (tier="scene"); optional ASCII map.apply_layout— Builds a layout into an open scene under[Generated Layout]plus the level's deploy cells and enemy spawns (one Undo group, never saved), then reports grid and physics tiers.render_layout_topdown— Orthographic top-down JPEG of the board or a cell region with grid lines and deploy/enemy markers;cut_heightclips roofs to show interiors.query_level_catalog— Finds level pieces by role, cover, footprint and name as compact rows, fromAssetCatalog/level-catalog.jsonor, in a game project, the reviewed pieces of the overrides file; names the file it read.generate_asset_catalog(catalog="level")/describe_level_cards— Level catalog cards for prefabs (role, cover, visual and collider bounds at root scale 1,placementScale, root rotation) inAssetCatalog/level-catalog.json, keyed by GUID;describe_level_cardsmeasures given prefab paths and their footprint for a cell size without writing anything. Roles and scales can be overridden inAssetCatalog/LevelCatalogOverrides.json. See level catalog.find_asset_references— Finds assets/scenes referencing a specific asset path (AssetDatabase.GetDependencies).write_unity_script— Creates/overwrites a C# script (Assets/...cs) and triggers recompilation (AssetDatabase.ImportAsset/Refresh,CONFIRM_REQUIREDpattern).create_scriptable_object— Creates aScriptableObjectasset atomically withoutwrite_unity_script:Type.GetType+ assembly fallback,ScriptableObject.CreateInstance, field init viaSerializedObject(primitives, enums as"cross"→UnitId.cross,Vector3{x,y,z},Objectrefs asinstanceId/guid/{fileID,guid}),Undo.RegisterCreatedObjectUndo+AssetDatabase.CreateAsset/SaveAssets/Refresh. ValidatesAssets/+.asset, parent folder exists,ScriptableObjectsubclass,CONFIRM_REQUIREDon overwrite. Returns{instanceId,guid,path}.delete_asset— Deletes an asset viaAssetDatabase.DeleteAsset(supports Undo, validatesAssets/).refresh_assets— No-argument asset refresh after external disk edits; Unity decides whether compilation/reload is needed. See refresh workflow.get_compilation_status— Non-blocking snapshot (PENDING/SUCCESS/FAILED/NO_COMPILATION/UNKNOWN) — poll afterwrite_unity_scriptorrefresh_assets.
Editor & Runtime
get_screenshot— Capturesgame(Camera.main) orscene(Scene view) as JPEG;scenecanFrameafocus_instance_idbounds before capture.open_scene— Opens a scene by project-relative path. Defaultdirty_policy=failrefuses unsaved changes;savesaves first. Returns scene path + dirty state.enter_play/exit_play— Request Play/Edit Mode and wait for the idle terminal state (or a timeout carrying state); survives domain reload viapoll_play_state.poll_play_state—{isPlaying, transitioning, isCompiling, isUpdating, pendingOp, interactionMode}snapshot with no side effects.invoke_menu_item— Execute one Editor menu item by exact path; unknown paths are not-found errors.invoke_static— Invoke one public static zero-arg method by exact type/method names; returns the value as string (okfor void).set_editor_throttling—no_throttlingkeeps the Editor tick rate un-throttled while unfocused for long sessions;restore/defaultafterwards.get_console_logs— First line of the last 10 Console entries viaLogEntriesreflection;clear=Trueclears the Console after reading.
Lighting Diagnostics
get_lights_affecting_object— Lights within range of a target object using actual bounds distance, per-lighttype/intensity/range/cullingMask(usesGetLightsAffectingObject). URP rendering path and light limits are inget_project_settings(sections=["rendering"]).
Known Limitations (for Agents using this tool to read)
- Unity instance IDs last as long as the object, within one Editor session. Script recompiles, domain reloads, entering or exiting Play Mode and asset reimports (even with changed content) keep them. Reopening or reloading a scene gives its objects new IDs (asset IDs survive), as does deleting and recreating an object. Reimporting the open scene's own file, such as a recursive reimport of its folder, reloads the scene a few seconds later. After a scene change, re-run
get_scene_hierarchybefore reusing an ID from an earlier call.acquire_editor_referenceshandles are separate and must be reacquired after any reload. - 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.
- A background Editor may still be slower than a focused one.
refresh_assetsnow refreshes, compiles and reloads in a hidden Editor without refocusing it. Other work can still be throttled by Unity's Interaction Mode:poll_play_statereportsinteractionMode, and unless the user prefers otherwise, run Editor-driving sessions underset_editor_throttling("no_throttling")and restore it afterwards.
Reusable test project
TestProject consumes the local package and enables its
EditMode tests. Run bash scripts/test-unity.sh from the repository root to prepare
TMP/mesh fixtures and run the suite with Unity 2022.3.62f3. Generated resources,
Editor caches and results are ignored. The test-host README documents known
opt-in refresh checks and how to select focused suites.
Batch operations and prefab inspection
Use inspect_prefab_assets(paths, component, properties, limits?) to compare
selected serialized fields across resolved prefab hierarchies in one read-only
request, with structured numeric values and explicit truncation.
Use acquire_editor_references(instance_ids) followed by semantic_batch for
bounded Editor inspections or property edits. Edits support dry runs, expected
values, stale-reference checks and one named Undo group; partial application is
possible. See usage, limits, failure semantics and validation.
Imported model inspection
Use inspect_model_asset(path, include_details=False) to read mesh IDs, bounds,
geometry counts, imported transforms, importer scale/axis settings, material slots
and outgoing dependencies without changing assets or scenes. See
model inspection and deletion-reference assessment
for coordinate-space definitions, examples and tests.
Pertanyaan tentang Unity Semantic Bridge MCP
Tool apa yang disediakan Unity Semantic Bridge MCP?
Server ini menyediakan 39 tool, termasuk get_recent_unity_events, get_project_settings, get_scene_hierarchy, inspect_gameobject, acquire_editor_references.
Apakah ini berfungsi dengan UI Toolkit atau HDRP?
Tidak, bridge ini dioptimalkan untuk proyek yang menggunakan uGUI dan URP. Untuk UI Toolkit, HDRP, atau BiRP, Anda sebaiknya menggunakan Unity CLI resmi.
Apakah saya memerlukan lisensi Unity untuk menggunakan ini?
Tidak, bridge ini tidak terikat dengan Unity Licensing dan berjalan 100% secara lokal.
Bisakah saya menjalankan beberapa proyek Unity sekaligus melalui server ini?
Ya, Anda dapat mendukung beberapa Unity Editor sekaligus dengan menetapkan port bridge yang berbeda untuk setiap proyek.
Bagaimana agent tahu apa yang saya ubah di dalam scene?
Bridge ini menyediakan tools yang memungkinkan agent untuk melihat tindakan dan perubahan manusia melalui event Unity terbaru.