MCP2UNITY
Provides tools for interacting with the Unity Editor, enabling inspection and management of project scripts, assets, hierarchy, console output, runtime diagnostics, profiler data, change sets, and Editor/Test Framework actions.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
MCP2UNITY
Version: 0.5.2 (experimental backport) | Unity: 2022.3 LTS (validated on 2022.3.62f3) | Windows PowerShell companion
Latest validation (2026-11-10, PR #4): Unity EditMode suite 160/160 passed (0 failed, skipped or inconclusive; 55.21 seconds) after the target-scene EventSystem fix merged into
main. Reviewed actionc0a81ff40d63; no console errors, scene saved/clean. See CHANGELOG.
MCP2UNITY restarts the original Wasim Unity MCP Bridge from its v0.5.1 source instead of upgrading the transport to v0.6.0. The v0.5.1 standalone PowerShell companion and its Unity Editor file-IPC architecture are retained; 17 optional tools from v0.6.0 are backported into separate Editor modules. This rebuild has 21 original tool entries + 17 backported entries + 1 reviewed Transform tool + 8 uGUI tools = 47 advertised MCP tools.
Verification status: All 73/73 EditMode tests (Phases 1–3) passed in Unity 2022.3.62f3 with the connected MCP bridge advertising 47 tools and no reported compilation/Console errors. Canvas/Panel/Button/Styling/Layout creation was exercised end-to-end in the MuOnBaAr test scene, which was restored to five original root objects. Phase 4 PlayMode interactions passed 13/13, bringing the measured total to 120/120 Unity tests (107 EditMode + 13 PlayMode) on 2026-11-10, including 10/10 Phase 5 UI serialization and persistence tests. Direct live MCP-created UI Hide/Show interaction was also verified in Game View (target
activeSelfchanged false/true) and the temporary Canvas/EventSystem were removed; the original five scene roots were verified. Unity compilation and Console were clean after UPM update. No standalone Windows companion/player-build certification is implied.
Why this build?
Keep the v0.5.1 companion process, ngrok lifecycle, script-inspection tools, and existing script-change approval workflow.
Isolate v0.6.0 runtime inspection, rollback, scene/view diagnostics, profiler and Editor/Test Framework actions behind modular handlers.
Add only narrow communication patches for MCP image envelopes, JSON array preservation, request expiry, and no replay of interrupted operations.
Require local review for scene/script change sets and Editor actions. Neither can be approved remotely.
Related MCP server: upilot
Install from GitHub (UPM)
Back up the project. Remove the old
com.wasimdevelopment.unity-mcp-bridgepackage if it is installed; both packages retain the same Editor assembly name and must not be installed together.In Unity 2022.3, open Window > Package Manager > + > Add package from git URL.
Enter:
https://github.com/MusafirEx/MCP2UNITY.gitAllow Newtonsoft JSON 3.2.1 and Unity Test Framework 1.1.33 dependencies to resolve. Check the Console for compile errors before starting anything.
Open Window > Wasim Development > Unity MCP Bridge, configure the Windows PowerShell executable and ngrok. Close any companion from an earlier installation before starting this one.
Click Start Companion and run Local MCP Self-Test. It should advertise 47 tools and complete a
unity_get_statusround trip. Use the private MCP endpoint generated by the bridge, not an unauthenticated public URL.
This URL installs from the repository's default branch, main. To explicitly select it, append #main to the URL. To keep a reproducible package version, pin a specific commit using #<commit-sha> instead. Unity Package Manager resolves Git revisions when the package is installed or updated; it does not automatically fetch every new commit. The former #rebuild/v051-backports install link is no longer recommended.
The tool catalog is visible only when the companion and Unity IPC are running. If requests fail during compilation, wait until Unity finishes importing before trying them again. A request that times out or is interrupted is intentionally not replayed.
Capability groups
Group | Tools |
v0.5.1 project, scripts, assets, hierarchy, animator, console and script proposals | 21 |
v0.6.0 runtime, capture, trace, change sets, diagnostics, references, profiler, editor/test actions | 17 |
Reviewed Transform position / Euler rotation / scale tool | 1 |
uGUI Canvas, element creation, RectTransform editing and hierarchy inspection (phase 1) | 4 |
Reviewed uGUI styling / LayoutGroup configuration (phase 2) | 2 |
Advanced uGUI controls, guarded GameObject deletion and Button event binding (phase 3) | 2 |
Advertised total | 47 |
See the 17 backported tool specifications and the backport matrix.
Change sets and Editor actions
The unity_set_transform tool prepares local/world Position, Euler Rotation and Scale changes (absolute or relative) as reviewed change sets. It does not modify the scene until approved locally. World scale on nonuniformly scaled parents is rejected; details and examples.
Enable the specific permissions in the bridge window, then review local proposals through Window > Wasim Development > Change Sets and Actions. Approval and rollback are local actions, not public MCP endpoints. Review every proposed operation; Unity callbacks and project tests may execute project-defined code.
Unity uGUI Phases 1–4
The following eight uGUI MCP tools are included in the catalog:
unity_create_canvas— queue creation of a Canvas, CanvasScaler, GraphicRaycaster and optional EventSystem.unity_create_ui— queue Panel, Image, Button, legacy Text, TextMeshProUGUI, Slider, Toggle, InputField or ScrollView creation under an existing Canvas; each element uses RectTransform.unity_set_rect_transform— queue Anchor Min/Max, Pivot, Size Delta or Anchored Position edits.unity_inspect_ui— read a bounded uGUI hierarchy, including RectTransform, text, colors, button interactability and LayoutGroup details.unity_set_ui_property— submit reviewed edits of text, font size, graphic color, interactable, raycastTarget, Image fill and sprite asset reference.unity_set_ui_layout— submit reviewed Horizontal/Vertical/Grid LayoutGroup configuration including spacing, padding, cell size and column/row constraints.unity_bind_button_event— only binds a persistent Button.onClick → GameObject.SetActive(bool) targeting a UI object under the same Canvas; arbitrary event targets/methods are rejected.unity_delete_gameobject— propose deletion of a saved scene GameObject with exact-name confirmation, a maximum subtree size (≤100), Unity Undo, local approval, and scene-file backup. Prefab instances/assets are protected.
Write tools only propose locally reviewed changes, so the Unity Review window must approve them. No remote approval endpoint is added. Creation operations support aliases (including $createdCanvas and $createdUi for dedicated calls) and retain scene-backup rollback.
See Unity uGUI MCP tools for schemas and test scope. UI Toolkit/UXML, arbitrary runtime callback method bindings, and advanced Button events beyond allowlisted SetActive(bool) are not supported. All 73 Phase 1–3 EditMode tests passed in Unity 2022.3.62f3, and the direct Canvas/Panel/Button/Styling/Layout MCP integration test succeeded. Phase 4 adds 13 separate PlayMode tests of actual UI event dispatch and input behavior. All 13/13 PlayMode tests passed through the reviewed Unity Test Runner action on 2026-11-10; PlayMode fixture tests do not by themselves demonstrate serialized MCP event persistence or clicks in every target game scene. The rollback guard correctly blocked an unsafe restore when scene files diverged; temporary UI was removed manually, and the original five root objects were verified.
Phase 6 — security and recovery tests (verified)
Tests/Editor/SafetyRecoveryIntegrationTests.cs adds 12 new EditMode safety regressions covering path constraints, stale/deferred scene write protection, deletion hierarchy guards, rollback divergence, and interrupted IPC request handling. All 12/12 passed on 2026-11-10 in Unity 2022.3.62f3, action abef18ce2b4b, run 4bfd294e-6c1e-48a6-9a34-839891d3c8bd (4.28s; no failed, skipped or inconclusive tests). Cumulative verified result: 108/108 automated tests (95 EditMode + 13 PlayMode). Live Phase 5 Hide/Show Game View clicks separately passed and are not included in this automated count.
Phase 7 — final MCP contract suite (verified)
Tests/Editor/FinalContractIntegrationTests.cs adds 12 EditMode tests for the 47-tool catalog, schema strictness and bounds, permission hints, stable read-only MCP responses, and invalid-input rejection. All 12 Phase 7 tests PASSED on 2026-11-10 using the refreshed UPM package and the corrected hierarchy test (action 5be3bb8c8c20, run 58d6361f-d8ec-4086-a42c-fd66d9bd12ea, 3.44s, zero failed/skipped/inconclusive). Cumulative automated result: 120/120 (107 EditMode + 13 PlayMode). Unity Editor tests alone do not certify an end-to-end external MCP client, Windows companion process survival, ngrok reconnection or player builds.
Windows Companion and ngrok transport validation (in progress)
The 120/120 Unity automated regression tests remain verified. A separate short live ChatGPT-to-Unity read-only burst passed 12/12 MCP calls (401–1096 ms per call, 626 ms mean) with stable Companion PID, ngrok reporting Ready, and an unchanged five-root gameplay scene. A reviewed Unity Editor script compile/domain reload was also verified (27efd2959d84): Editor.log confirms the reload and the running Companion retained PID 20996, ngrok reported Ready, and Unity IPC resumed. Those earlier domain-reload observations were separate from the later verified Windows public HTTPS and restart checks described below.
A targeted PowerShell reliability patch in Companion~/wdmcp-companion.ps1 replaces the prior delete-then-move JSON writer with atomic File.Replace/File.Move and bounded retries. The offline PowerShell function regression has now passed on Windows (all reported assertions, including 18 held-reader JSON replacements, cleanup, JSON null and image responses, and heartbeat recovery). The Tests~/test-companion-stability.ps1 local/ngrok/restart observer has now passed live Windows execution for a 12/12 local soak and a controlled Companion restart. The script never prints private endpoints or performs automatic restarts.
Controlled Windows Companion restart now PASSED (2026-11-10): 3/3 pre-restart local MCP handshakes, followed by direct local and public ngrok HTTPS JSON-RPC success (47 tools) after a user-initiated restart. Companion PID changed 24496 → 10260; no status-file read recoveries occurred. Unity scene and console stayed clean. These results verify a controlled restart, not unattended crash or prolonged-network-outage recovery.
Direct Windows transport soak now PASSED: 12/12 local MCP handshakes (mean 290 ms, maximum 352 ms), actual public HTTPS ngrok MCP handshake (47 tools), and zero observed status-read recoveries/retries in that run. Prior transient status-file failures are documented; manual Companion restart/reconnect remains pending.
See the Windows/ngrok stability validation plan for commands, manual approval points and acceptance criteria.
Verification on your Windows workstation
Run the PowerShell regression tests from the package root:
& '.\Tests~\test-companion-functions.ps1'For Unity Edit Mode tests, add the installed package name to your test project's Packages/manifest.json:
"testables": ["com.musafirex.mcp2unity"]Then run Window > General > Test Runner > EditMode > BridgeIntegrationTests or:
& '.\Tests~\run-unity-tests.ps1' -UnityEditor 'C:\Program Files\Unity\Hub\Editor\2022.3.22f1\Editor\Unity.exe' -ProjectPath 'C:\YourTestProject'Tests require a disposable project with a backup. Also verify Console reading, script inspection, camera image transport, tracing, change-set rollback, compile/reload continuity, and ngrok reconnection using the actual Windows setup. VRChat behavior still needs testing in VRChat clients; Unity/ClientSim inspection is not authoritative network verification.
Architecture
MCP Client -> ngrok HTTPS -> PowerShell companion (v0.5.1 base)
|
Library/ file IPC
|
Unity Editor dispatcher
| |
21 legacy tools 17 modular toolsNo model API key is embedded.
Editor-only assembly; no runtime/player build bridge.
Paths and user-approved changes are restricted to the permitted project locations.
Keep private capability URLs and ngrok tokens out of public Git commits and issue logs.
Source and license
Original source: wasim-development/wasim-unity-mcp-bridge v0.5.1 (commit 9061958a372df692daf056ba03b5aff283b6d99d). Feature reference: v0.6.0 (commit bd4f758e7fde2a76c9b4c032e6882675b3e934df). Original paths and Unity .meta GUIDs are preserved. The upstream restrictive LICENSE.md is retained: publication/redistribution requires permission from Wasim Development.
Unity uGUI Phase 4 — PlayMode interaction tests (verified)
Tests/PlayMode/WasimUnityMcpBridge.PlayMode.Tests.asmdef and UiRuntimePlayModeTests.cs add 13 Unity PlayMode tests for Button pointer clicks, SetActive callbacks, disabled Buttons, GraphicRaycaster hit tests, Slider value/range/whole-numbers and silent updates, Toggle pointer clicks and interactability, legacy InputField text/limits/callbacks, and ScrollRect normalized movement and drag. They use transient Canvas/EventSystem fixtures and destroy them after each test; no gameplay scene assets are saved. These tests exercise the Unity runtime interaction layer; the MCP-created hierarchy and persistent Button listener are separately checked by the 73 EditMode tests. A live end-to-end MCP UI PlayMode test is still recommended. 13/13 tests passed on 2026-11-10 in Unity 2022.3.62f3 (reviewed action f197a999ff82, 0 failed/skipped/inconclusive); combined EditMode and PlayMode automated results are 86/86 passed.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Start and manage Reason cloud coding agents, projects and sessions from any MCP client.
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Read and write shared BitsWeave context, projects, tasks, and work sessions through MCP.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAllows MCP clients like Claude Desktop or Cursor to perform Unity Editor actions, including asset management, scene modification, and game mechanic testing.22MIT
- AlicenseNot gradedqualityAmaintenanceUnity Editor automation bridge for AI agents and MCP clients, enabling inspection, control, and diagnostics of the Editor.MIT
- AlicenseNot gradedqualityAmaintenanceUnity Editor adapter for the DCC MCP ecosystem, providing tools to inspect and modify Unity projects, scenes, builds, and diagnostics through a WebSocket bridge.86 PyPI1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to access Unity Editor project information, scene hierarchies, object inspection, selection state, and console logs through MCP.MIT