mcp-unity: Skill for Claude Code

mcp-unity development notes

Hard-won knowledge from actually using and extending mcp-unity in this repo. Read the section relevant to your task before you start, not after you hit the bug.

If you're modifying the mcp-unity package itself

The Unity project that actually runs this code (My project (1)) pulls it as a git package, not a local reference — editing files in this repo does nothing to the running Unity Editor until you:

1. Edit the C# (Editor/Tools/*.cs, McpUnityServer.cs) and/or TypeScript (Server~/src/tools/*.ts, index.ts)
2. New .cs files need a .meta file — Unity treats git packages as immutable and silently drops any asset without one (no error, the type just doesn't exist, giving a confusing CS0246 in an unrelated file). Generate a GUID (powershell -Command "[guid]::NewGuid().ToString('N')") and write the meta in the same format as a sibling file.
3. cd Server~ && npm run build to catch TypeScript errors
4. Commit (no AI co-author line — this user's preference), push to origin/main
5. In Unity: Package Manager → In Project → MCP Unity → Update (or remove/re-add if no Update button). This triggers a domain reload.
6. Verify via get_console_logs — check the PackageCache folder hash in any log line matches your new commit SHA, and confirm no compile errors before using the new tool.

Tool registration is two-sided and easy to half-do: a new tool needs a Unity McpToolBase subclass registered in McpUnityServer.cs RegisterTools(), and a Node registerXTool() in Server~/src/tools/*.ts registered in index.ts. Forgetting either side gives a confusing "tool not found" or silently does nothing.

Tool gotchas (don't rediscover these empirically)

• reparent_gameobject does not reorder the Hierarchy. It changes parent only; Unity's SetParent is a no-op for sibling index when the parent is unchanged, and even a genuine temp-parent bounce doesn't reliably reorder. Use set_sibling_index instead (absolute siblingIndex, or insertAfterInstanceId/insertBeforeInstanceId relative to a sibling).
• duplicate_gameobject on a nested child under a scaled/rotated parent used to corrupt the clone's transform. Fixed by instantiating with the parent specified directly (Instantiate(original, parent)) instead of parentless-then-reparent. If you ever see a duplicate land at a wildly wrong position/rotation/scale, this is the failure mode to suspect.
• Component fields that reference other scene objects (a Transform, Rigidbody, or another Component) go through update_component's componentData using {"instanceId": N} or {"objectPath": "Parent/Child"} — not {"path": ...}/{"guid": ...}, which are asset-only (AssetDatabase). If the target field type doesn't match the resolved object directly (e.g. field is Rigidbody but you passed the GameObject's ID), it falls back to GetComponent automatically. List<T>/array fields accept a JSON array of the same per-element shapes.
• Collider-derived components (including WheelCollider) are read via SerializedObject, not reflection. They used to be fully skipped ("_skipped": "Detailed property serialization skipped for safety") because some of their reflected C# properties are native-backed getters that can crash the Editor. get_gameobject/get_gameobject resource now dump these via the same SerializedObject/SerializedProperty API update_component already trusts for writes, so radius, isTrigger, suspensionSpring, etc. read back correctly. Native-plugin components (Pathfinding/FMOD namespaces) are still fully skipped — that skip is unrelated and still necessary.
• set_play_mode_status action:"play"/"stop" used to frequently return "Connection failed" or time out. Root cause: entering/exiting Play mode synchronously fires ExitingEditMode, which unconditionally closes the WebSocket (StopServer) — this could race the in-flight response, and separately, the Node bridge used to reject all pending requests on any transient WebSocket error event (not just a terminal disconnect), which fired on the same reset. Both are fixed: Unity defers the actual mode transition to the next editor tick (via EditorApplication.delayCall) so the response is queued to send first, and Node no longer rejects pending requests on a bare connection error — only on a genuinely terminal disconnect. The action should now resolve normally without a manual sleep-and-poll workaround.
• Unity discards all runtime changes to existing scene objects when you exit Play mode (auto-revert to the edit-time saved state). If you need to inspect what happened during a Play session, query while still in Play mode — don't stop first.
• GameObject lookup by instanceId/objectPath now goes through one shared resolver (Editor/Utils/GameObjectResolver.cs) used by every tool. It searches all loaded scenes and includes inactive objects, and a bare name that matches more than one object returns an ambiguous_reference_error listing every candidate instead of silently picking one. Previously, whether an inactive object or an object in a non-active loaded scene could be found at all depended on which specific tool you called (four independent, disagreeing implementations existed) — that's no longer the case.
• Prefer batch_execute for any run of >2-3 related tool calls — it's dramatically faster than sequential calls and each op gets its own success/failure in the summary.