Unity Semantic Bridge MCP server
2026년 10월 26일 커밋AI 에이전트가 실시간 씬 조작, 계층 구조 검사 및 uGUI 제작을 위해 라이브 Unity Editor 세션과 상호작용할 수 있도록 지원합니다.
다른 이름 Programalyst/unity-semantic-bridge
- 스타
- 8
- Tools
- 39
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 10월 26일
- 라이선스
- Apache-2.0
Unity Semantic Bridge MCP란?
Unity Semantic Bridge은(는) MCP server입니다. AI 에이전트가 실시간 씬 조작, 계층 구조 검사 및 uGUI 제작을 위해 라이브 Unity Editor 세션과 상호작용할 수 있도록 지원합니다. 39개 도구를 제공합니다. 예: get_recent_unity_events, get_project_settings, get_scene_hierarchy.
프로젝트 README에서 생성된 요약
Unity Semantic Bridge MCP server 정보
Unity Semantic Bridge는 AI 에이전트와 라이브 Unity Editor 세션 간의 특화된 연결을 제공합니다. 정적인 프로젝트 파일만 조회하는 도구와 달리, 이 MCP server는 에이전트가 사용자의 실시간 변경 사항을 관찰하고 활성화된 씬과 직접 상호작용할 수 있도록 합니다. URP 및 uGUI 프로젝트를 작업하는 개발자를 위해 설계되었으며, 씬 계층 구조, 컴포넌트 인스펙터 값 및 최근 에디터 이벤트에 대한 높은 가시성을 제공합니다.
브릿지를 사용하려면 Unity 패키지를 설치하고 uv를 사용하여 Python MCP server를 로컬에서 실행해야 합니다. 설정 시 Python 클라이언트를 특정 포트를 통해 Unity HTTP listener에 연결해야 하며, 여러 에디터 프로젝트를 동시에 지원하도록 구성할 수 있습니다. 서버는 핵심 기능을 위해 Unity 라이선스나 외부 API 키를 요구하지 않고 완전히 로컬에서 작동합니다. 속성 일괄 편집, 프리팹 비교 및 복잡한 uGUI 제작 작업을 위한 특화된 도구를 포함하고 있어, 에이전트의 작업이 에디터의 undo 시스템에 통합되도록 보장합니다.
활용 사례
- 1사용자 에디터 변경 사항 모니터링에이전트가 개발자가 씬에서 수정한 내용을 추적하여 동기화 상태를 유지할 수 있습니다.
- 2UI 생성 자동화개발자가 에이전트에게 전체 사용자 인터페이스 계층 구조를 구축하고 레이아웃을 잡도록 지시할 수 있습니다.
- 3속성 일괄 업데이트 수행에이전트가 안전 검사 및 undo 지원 기능을 활용하여 여러 컴포넌트 값을 한 번에 수정할 수 있습니다.
- 4복잡한 캐릭터 리그 검사에이전트가 캐릭터의 스켈레톤을 탐색하여 구조를 파악할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Unity Semantic Bridge MCP 도구 39
README에서 감지됨get_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 | — |
도구 39개 모두 보기도구 수 줄이기
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 | — |
자동 검사
2026년 11월 15일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능programalyst/unity-semantic-bridge is public and reachablegithub.com/programalyst/unity-semantic-bridge ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-26github.com/programalyst/unity-semantic-bridge ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음39 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기Unity 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.
Unity Semantic Bridge MCP 질문
Unity Semantic Bridge MCP는 어떤 도구를 제공하나요?
39개 도구를 제공합니다. 예: get_recent_unity_events, get_project_settings, get_scene_hierarchy, inspect_gameobject, acquire_editor_references.
UI Toolkit이나 HDRP에서도 작동하나요?
아니요, 이 브릿지는 uGUI 및 URP를 사용하는 프로젝트에 최적화되어 있습니다. UI Toolkit, HDRP 또는 BiRP의 경우 공식 Unity CLI를 사용해야 합니다.
사용하려면 Unity 라이선스가 필요한가요?
아니요, 브릿지는 Unity 라이선스와 연동되지 않으며 100% 로컬에서 실행됩니다.
이 서버를 통해 여러 Unity 프로젝트를 동시에 실행할 수 있나요?
네, 각 프로젝트에 고유한 브릿지 포트를 할당하여 여러 Unity Editor를 동시에 지원할 수 있습니다.
에이전트는 제가 씬에서 무엇을 변경했는지 어떻게 알 수 있나요?
브릿지는 에이전트가 최근 Unity 이벤트를 통해 사용자의 작업과 변경 사항을 확인할 수 있는 도구를 제공합니다.