Unity Semantic Bridge MCP server
Commit 26. Okt. 2026Ermöglicht es AI-Agents, mit Live-Unity-Editor-Sessions zu interagieren, um Szenen in Echtzeit zu manipulieren, die Hierarchy zu inspizieren und uGUI zu erstellen.
Auch bekannt als Programalyst/unity-semantic-bridge
- Stars
- 8
- Tools
- 39
- Downloads, 30 Tage
- —
- Neueste Version
- —
- Letzter Commit
- 26. Okt. 2026
- Lizenz
- Apache-2.0
Was ist Unity Semantic Bridge MCP?
Unity Semantic Bridge ist ein MCP server. Ermöglicht es AI-Agents, mit Live-Unity-Editor-Sessions zu interagieren, um Szenen in Echtzeit zu manipulieren, die Hierarchy zu inspizieren und uGUI zu erstellen. Er stellt 39 Tools bereit, etwa get_recent_unity_events, get_project_settings, get_scene_hierarchy.
Zusammenfassung generiert aus dem README des Projekts
Über Unity Semantic Bridge MCP server
Der Unity Semantic Bridge bietet eine spezialisierte Verbindung zwischen AI-Agents und Live-Unity-Editor-Sessions. Im Gegensatz zu Tools, die nur statische Projektdateien abfragen, ermöglicht dieser Server es Agents, Echtzeit-Änderungen durch Menschen zu beobachten und direkt mit der aktiven Szene zu interagieren. Er ist für Entwickler konzipiert, die mit URP- und uGUI-Projekten arbeiten, und bietet eine hohe Sichtbarkeit der Scene Hierarchy, der Component Inspector Werte und aktueller Editor-Events.
Um den Bridge zu nutzen, musst du ein Unity-Package installieren und den Python MCP server lokal mit uv ausführen. Das Setup erfordert die Verbindung des Python-Clients mit dem Unity HTTP Listener über spezifische Ports, die so konfiguriert werden können, dass sie mehrere gleichzeitige Editor-Projekte unterstützen. Der Server arbeitet vollständig lokal und benötigt weder Unity-Lizenzen noch externe API-Keys für seine Kernfunktionen. Er enthält spezialisierte Tools für Batch-Property-Edits, Prefab-Vergleiche und komplexe uGUI-Authoring-Aufgaben, wobei sichergestellt wird, dass die Aktionen des Agents in das Undo-System des Editors integriert werden.
Was du damit machen kannst
- 1Menschliche Editor-Änderungen überwachenEin Agent kann verfolgen, was ein Entwickler in der Szene geändert hat, um synchron zu bleiben.
- 2UI-Erstellung automatisierenEin Entwickler kann einen Agent anweisen, komplette User-Interface-Hierarchien zu bauen und zu layouten.
- 3Batch-Property-Updates durchführenEin Agent kann mehrere Component-Werte gleichzeitig mit Sicherheitsprüfungen und Undo-Support ändern.
- 4Komplexe Character Rigs inspizierenEin Agent kann das Skelett eines Characters durchlaufen, um dessen Struktur zu verstehen.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
Unity Semantic Bridge MCP tools 39
Erkannt aus dem 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 | — |
Alle 39 Tools anzeigenWeniger Tools anzeigen
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 | — |
Automatisierte Checks
Geluften am 15. Nov. 2026Vollständiger Bericht →Noch nicht verifiziert. Ein Server benötigt einen Score von 80, keine kritischen Befunde und genug Daten für unsere Prüfung. Wie die Checks funktionieren · Was du für mehr Punkte verbessern kannst
- Source Repository verknüpft und erreichbarprogramalyst/unity-semantic-bridge is public and reachablegithub.com/programalyst/unity-semantic-bridge ↗Bestanden
- Paket nennt dieses Repository als QuelleNicht geprüft
- Build-Provenienz (Sigstore-Attestierung)Nicht geprüft
- Open Source Lizenz (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Bestanden
- Commit oder Release im letzten JahrLast commit or release 2026-10-26github.com/programalyst/unity-semantic-bridge ↗Bestanden
- OpenSSF ScorecardNicht geprüft
- Package-Name ähnelt keinem populären PackageNicht geprüft
- Keine kritischen Advisories im Paket oder seinen AbhängigkeitenNicht geprüft
- Keine versteckten Anweisungen an das Modell39 tool descriptions and the README read; no override phrases, credential paths or hidden charactersBestanden
- Destruktive Tools sind markiertNicht geprüft
- Remote-Endpoint beantwortet den MCP-HandshakeNicht geprüft
README
Auf GitHub ansehenUnity 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 Fragen
Welche Tools bietet Unity Semantic Bridge MCP?
Er stellt 39 Tools bereit, darunter get_recent_unity_events, get_project_settings, get_scene_hierarchy, inspect_gameobject, acquire_editor_references.
Funktioniert das mit UI Toolkit oder HDRP?
Nein, dieser Bridge ist für Projekte optimiert, die uGUI und URP nutzen. Für UI Toolkit, HDRP oder BiRP solltest du das offizielle Unity CLI verwenden.
Benötige ich eine Unity-Lizenz, um das zu nutzen?
Nein, der Bridge ist nicht an die Unity-Lizenzierung gebunden und läuft zu 100 % lokal.
Kann ich mehrere Unity-Projekte gleichzeitig über diesen Server laufen lassen?
Ja, du kannst mehrere Unity Editors gleichzeitig unterstützen, indem du jedem Projekt eigene Bridge-Ports zuweist.
Woher weiß der Agent, was ich in der Szene geändert habe?
Der Bridge stellt Tools bereit, mit denen Agents menschliche Aktionen und Änderungen über aktuelle Unity-Events einsehen können.