|
| 1 | +# MCP Unity |
| 2 | + |
| 3 | +> MCP Unity is an open-source implementation of the Model Context Protocol (MCP) for the Unity Editor. |
| 4 | +> It connects a C# Unity Editor package with a Node.js/TypeScript server over WebSockets and exposes |
| 5 | +> high-level "tools" and "resources" so language-model agents and other automated clients can safely |
| 6 | +> inspect, test, and modify Unity projects in real-time. |
| 7 | + |
| 8 | +This repository consists of two coordinated halves that communicate using JSON-encoded MCP messages: |
| 9 | + |
| 10 | +- **Editor/** – Unity package that starts an internal WebSocket server and registers C# MCP tools & resources. |
| 11 | +- **Server/** – Node.js/TypeScript application that runs outside Unity, connects to the Editor server, and |
| 12 | + re-exposes identical MCP tools/resources for AI assistants. |
| 13 | + |
| 14 | +Together they allow AI coding assistants (e.g. Windsurf, Cursor, Claude Code, GitHub Copilot) to drive the Unity Editor headlessly, |
| 15 | +automate scene and asset management, run tests, install packages, and gather diagnostics. |
| 16 | + |
| 17 | +## Docs |
| 18 | +- [Project README](README.md): Full feature list, installation, and getting-started guide. |
| 19 | +- [Installation guide](README.md#installation): Step-by-step setup instructions. |
| 20 | +- [Unity Editor Tools source](Editor/Tools/): C# classes that implement individual editor actions. |
| 21 | +- [Node.js Tools source](Server~/src/tools/): TypeScript wrappers that forward requests to Unity. |
| 22 | + |
| 23 | +## Tools |
| 24 | +- [`execute_menu_item`](README.md#mcp-server-tools): Executes Unity Editor menu items by path. |
| 25 | +- [`select_gameobject`](README.md#mcp-server-tools): Selects GameObjects in the Unity scene by path or instance ID. |
| 26 | +- [`update_gameobject`](README.md#mcp-server-tools): Creates or updates GameObjects (name, tag, layer, active/static). |
| 27 | +- [`update_component`](README.md#mcp-server-tools): Adds or edits component fields on GameObjects. |
| 28 | +- [`add_package`](README.md#mcp-server-tools): Installs Unity packages via the Package Manager. |
| 29 | +- [`run_tests`](README.md#mcp-server-tools): Runs Unity Test Runner tests (EditMode/PlayMode). |
| 30 | +- [`send_console_log`](README.md#mcp-server-tools): Sends a console message to the Unity Editor log. |
| 31 | +- [`add_asset_to_scene`](README.md#mcp-server-tools): Adds an AssetDatabase asset to the current scene. |
| 32 | + |
| 33 | +## Resources |
| 34 | +- [unity://menu-items](README.md#mcp-server-resources): Returns all available Unity menu items. |
| 35 | +- [unity://scenes-hierarchy](README.md#mcp-server-resources): Current scene hierarchy tree. |
| 36 | +- [unity://gameobject/{id}](README.md#mcp-server-resources): Detailed info for a specific GameObject. |
| 37 | +- [unity://logs](README.md#mcp-server-resources): Unity console log entries. |
| 38 | +- [unity://packages](README.md#mcp-server-resources): Installed/available Unity packages. |
| 39 | +- [unity://assets](README.md#mcp-server-resources): AssetDatabase search results. |
| 40 | +- [unity://tests/{testMode}](README.md#mcp-server-resources): Test metadata for EditMode/PlayMode. |
| 41 | + |
| 42 | +## Optional |
| 43 | +- [Model Context Protocol specification](https://modelcontextprotocol.io/spec): Formal protocol definition for MCP. |
| 44 | +- [Unity Editor](https://unity.com/releases/editor/archive): Official Unity Editor download and documentation. |
| 45 | +- [Node.js](https://nodejs.org/en/download/): JavaScript runtime used for the MCP server backend. |
| 46 | +- [WebSocket-Sharp (C#)](https://github.com/sta/websocket-sharp/tree/master/websocket-sharp/Server): C# WebSocket server library used in the Unity package. |
0 commit comments