unity-mcp

Control a running Unity Editor from Claude (or any MCP client). Two parts:

• unity-plugin/ — C# Editor plugin. Runs a JSON-RPC-over-HTTP server on localhost:8090 inside the Unity Editor. No dependencies beyond the UnityEditor API.
• server/ — TypeScript MCP server (@modelcontextprotocol/sdk). Exposes 21 unity_* tools and 2 read-only resources, and talks to the plugin over localhost.

Claude Code ──stdio──> server (MCP) ──HTTP/JSON-RPC──> Unity Editor plugin

Setup

1. Unity plugin

This repo's test-project/ gets the plugin via a copy sync:

.\tools\sync-plugin.ps1

For any other Unity project (2021.3+), copy unity-plugin/Editor/ into your project's Assets/ (any subfolder). Do not use a directory junction or symlink — Unity's asset refresh does not reliably detect changes made through them.

Open the project in the Unity Editor. On load, the Editor console logs:

[UnityMcp] HTTP server listening on 127.0.0.1:8090

2. MCP server

cd server
npm install
npm run build

3. Connect Claude Code

claude mcp add unity --scope user -- node <absolute-path-to-repo>\server\dist\index.js

Restart Claude Code, then try: "Create a cube named Hero in the Unity scene and add a Rigidbody."

A scripted end-to-end check (no Claude needed) lives at server/e2e.mjs; with the Editor open, node server/e2e.mjs runs the full create-script-compile-play-console loop and writes docs/e2e-example.md.

Configuration

| Setting | How | |---|---| | Port (default 8090) | Set UNITY_MCP_PORT in BOTH the Unity Editor's environment and the MCP server's environment. |

Tool naming

unity_<domain>_<action> — domains: scene, script, console, playmode, compile. Resources: unity://scene/hierarchy, unity://console/logs.

Known limitations

• Console buffer resets on domain reload (recompile, play-mode enter/exit). unity_console_read ids restart; treat lastId as invalid after a reload.
• Async transitions: unity_playmode_enter/exit, unity_script_create/write, and unity_compile_request return immediately and the Editor goes briefly unreachable while it reloads. Poll unity_playmode_status / unity_compile_status. After isCompiling goes false the new domain may still be loading for a few seconds — retry once if a new type is "unknown".
• Untitled scenes require an explicit path on unity_scene_save (a native save dialog would block the Editor otherwise).
• Localhost only. The plugin binds 127.0.0.1 and has no auth — do not port-forward it.
• Play-mode edits don't persist after exiting play mode (Unity behavior; mutating tools warn when this applies).