dcc-mcp-unity

Unity Editor adapter for the DCC Model Context Protocol ecosystem. It ships a UPM Editor package, a loopback WebSocket bridge, and typed project, scene, build, and diagnostic tools.

The adapter supports all Unity Editor versions from Unity 2018.4.25f1 onwards, covering every 2018–2024 LTS release and Unity 6. CI pins the 2018 baseline, the 2021.3 baseline, and the current stable Unity 6 release instead of using a drifting latest tag. The .NET 4.x Equivalent scripting runtime is required when using Unity 2018.4.

Part of the DCC-MCP host matrix

dcc-mcp-unity — Unity Editor adapter and typed game-authoring skills for DCC-MCP.

It is one of 47 host adapters in the DCC-MCP catalog. Every adapter speaks the same MCP protocol and builds on the same core runtime contract; each one exposes the tools its own host needs on top of that.

• All host adapters and install metadata
• Host matrix on the core README
• Showcase

This block is generated from the catalog entry in dcc-mcp-catalog.yml. Re-run the generator after changing the catalog.

Install

pip install dcc-mcp-unity
dcc-mcp-unity install --project /path/to/UnityProject --dry-run
dcc-mcp-unity install --project /path/to/UnityProject --yes

Open or restart the Unity project so Package Manager compiles DCC-MCP Unity, then run:

dcc-mcp-unity

See the installation guide for JSON output, verification, upgrade, uninstall, rollback, and troubleshooting details. The legacy dcc-mcp-unity-install entry point remains available during migration.

The MCP endpoint uses a free loopback port and is registered for gateway discovery. Set DCC_MCP_UNITY_PORT=8765 before starting the server only when a fixed direct endpoint is needed. The Editor package reconnects to the loopback bridge at ws://127.0.0.1:3852; set DCC_MCP_UNITY_BRIDGE_PORT before the MCP server and DCC_MCP_UNITY_BRIDGE_URL before Unity starts to override it. DCC_MCP_UNITY_BRIDGE_TIMEOUT may increase the 60-second RPC timeout but cannot lower it; queued Editor work expires first so timed-out mutations are not executed later.

Transport connection does not imply that Unity's Editor update loop is responsive. The adapter probes that loop separately; when a native modal dialog blocks it, subsequent typed calls fail quickly with recovery guidance instead of waiting for the bridge timeout. Use dcc-mcp-cli ui-control for the same instance, or search ui-control and load Core's app-ui compatibility Skill from an MCP client. The recovery session must bind the exact Unity PID/HWND through dcc-cua, dismiss one modal action, and then verify a fresh readiness probe before retrying.

The default bridge targets one Unity Editor. For concurrent Editors, run one adapter per Editor and assign each pair a unique bridge port and URL before starting either process.

Source writes are disabled by default. An operator may set DCC_MCP_UNITY_ALLOW_SOURCE_WRITES=1 before starting Unity to enable the bounded upsert_text_asset tool. It accepts only allowlisted UTF-8 text extensions below Assets, caps encoded content at 256 KiB, rejects JSON-unsafe control characters, requires compare-and-swap state, rejects reparse points, and replaces files atomically. The adapter exposes no delete, arbitrary path, shell, or code-evaluation tool.

The per-asset lock is cooperative: it serializes DCC-MCP writers but cannot stop another same-user process from ignoring the lock or swapping a junction or symlink after path validation and before the operating system resolves a write. That same-user race is outside this in-process boundary. If an external replacement conflict is detected, the adapter performs no automatic rollback, preserves the displaced bytes in a unique .dccmcp-*.backup conflict backup, and does not write the target again after detection. A failed conflict job does not prove the target stayed unchanged; inspect both the target and backup before submitting another write.

Standalone sidecar

Hosts without an embedded Python runtime can use the PyOxidizer sidecar released with each version. The release asset contains the executable, its adjacent lib/ runtime, and SHA256SUMS. Configure the Unity package to start it on editor load by setting DCC_MCP_UNITY_SIDECAR_PATH; optionally set DCC_MCP_UNITY_SIDECAR_SHA256 to the published digest. The launcher is loopback-only, passes the Unity process id to --watch-pid, and uses a per-project pid file to avoid duplicate sidecars after assembly reloads.

For local development, run dcc-mcp-unity-standalone --bridge-port 3852 --watch-pid <unity-pid>.

Agent workflow

1. Load unity-project and call inspect_project before assuming project or editor state. Stop if the returned project is not the intended target or the Editor is compiling, updating, entering Play Mode, or playing.
2. Read an existing source with read_text_asset, then pass its SHA-256 to upsert_text_asset; use expected_sha256: absent only for creation. Keep the UUID request_id and poll inspect_job until it reports succeeded or failed.
3. Call refresh_and_compile, poll its job, and inspect read_console before entering Play Mode.
4. Load unity-scene and call inspect_scene immediately before using an instance ID. Treat IDs as opaque values and return them unchanged. Unity 6000.5+ emits decimal strings; older Editors retain integer output, and both forms are accepted as input.
5. Create GameObjects or change transforms through typed operations backed by Unity Undo, verify the hierarchy, then explicitly call save_scene.
6. In Tuanjie projects with its optional AI packages installed, load unity-tuanjie-ai, inspect the native CustomTool catalog, then submit or query only a freshly returned tool name. Native Codely sign-in, credits, downloads, and task recovery remain owned by Tuanjie.
7. Use set_play_mode before capture_game_view; capture requires active, unpaused Play Mode, focuses Game View, waits a rendered frame, and succeeds only after Unity decodes a nonzero PNG below Builds/DccMcp/Captures. Captures are limited to 32 MiB, 8192 pixels per axis, and 32M pixels total.
8. run_tests executes the installed Unity Test Framework in EditMode or PlayMode without spawning another Editor. Optional filters are exact fully-qualified test or fixture names. Poll the job and retain its request-scoped NUnit XML, SHA-256, outcome, and counts as test evidence; zero matches fail closed.
9. build_windows_player persists an active-target switch when needed, rejects dirty enabled scenes, and builds exactly the saved Build Settings scenes to a new UUID directory below Builds/DccMcp. Poll the job and launch the reported executable as a separate acceptance gate.
10. build_android_player applies the same persistent scene and request boundaries to APK or AAB output. It fails closed when Android support or required project signing is unavailable, never accepts signing secrets, restores the app-bundle setting, and reports BuildReport metadata plus the artifact size and SHA-256.

Do not replace a timed-out job with a new UUID. Reconnect and inspect the original request_id; Unity persists queued/running/succeeded/failed state across domain reloads and rejects reuse with different parameters.

Unity 2018 reloads Editor assemblies during normal Play Mode transitions, so the loopback socket will disconnect and reconnect. set_play_mode persists its waiting state before requesting the transition; a bridge disconnect is not completion or failure. After reconnection, inspect the same request_id for the observed terminal state.

No raw C# evaluation, shell command, or arbitrary filesystem write is exposed. The Editor bridge accepts only the methods implemented in DccMcpCommands and executes them on Unity's editor update loop. One persistent mutating job runs at a time. Mutations fail closed in incompatible Editor states. Requests, queued work, source text, scene snapshots, Console reads, and serialized responses have explicit size or lifetime budgets.

Tuanjie Engine

团结引擎 (Tuanjie Engine) is Unity China's localized distribution of Unity, tailored for the Chinese market with additional platform support and AI capabilities. DCC-MCP Unity detects and works with both standard Unity Editor builds and Tuanjie Engine builds without separate deployment — no additional configuration is needed.

When Tuanjie's optional AI packages are installed in the project, the unity-tuanjie-ai tool set becomes available. It exposes the native CustomTool catalog so agents can inspect available tools, submit requests, and query results through Tuanjie's Codely platform. Sign-in, credits, downloads, and task recovery remain owned by the Tuanjie runtime.

Validation boundary

Public CI validates Python 3.9 and 3.12 on Windows, macOS, and Linux; validates the bundled skill contracts; performs static checks for the UPM package and main-thread/Undo contracts; and builds the PyPI artifacts. Trusted pull requests, main, and the weekly schedule also compile the UPM package and run its command, scene, Undo, and validation tests through GameCI in Unity 2018.4.25f1, 2021.3.45f1, and 6000.5.4f1. Fork pull requests skip the licensed Editor jobs because GitHub does not expose repository secrets to forks. Licensed runs share one repository-wide queue across pull requests, main, releases, and schedules so a Personal seat is never activated concurrently. Each Editor also completes a real WebSocket hello → project.inspect → response smoke against the Python sidecar and records the reported Editor version as an artifact.

Development

uv sync --extra dev
uv run python -m pytest
uv run ruff check src tests tools
uv run ruff format --check src tests tools
uv run python tools/lint_skills.py
uv run python -m build
uv run python -m twine check dist/*

Unity and the Unity cube logo are trademarks of Unity Technologies. This independent adapter is not affiliated with or endorsed by Unity Technologies.