Content
# 🎮 Unity Editor MCP
Enable stable operation of MCP-supported AI clients in Unity Editor.
Compatible with Unity `2019.4 LTS` and later versions.
## ✨ Highlights
- 🚀 Unity Bridge starts automatically with Editor, listening on `127.0.0.1:8765` by default
- 🔎 MCP Server automatically detects Unity projects within the `8765-8775` port range
- 🧭 Supports multiple Unity project routes, with automatic selection by project path, project name, or runtime
- 🧱 Covers common editor operations such as scenes, Hierarchy, GameObject, Transform, Component, Asset, Prefab, scripts, etc.
- 🛠️ Built-in `Tools > Unity MCP` window for viewing status, logs, and permission switches
## 📦 Versions
| Module | Package / Version |
| --- | --- |
| Unity Bridge | `com.yys.unity-mcp-bridge@0.6.2` |
| MCP Server | `@luoluo123/unity-mcp-server@0.6.2` |
| Unity | `2019.4 LTS+` |
| Node.js | `18+` |
## ⚡ Quick Start
### 1. Install Unity Bridge
Open in Unity:
```text
Window > Package Manager > + > Add package from git URL...
```
Enter either address:
```text
https://gitee.com/furanzhang/unity-editor-mcp.git?path=/Packages/com.yys.unity-mcp-bridge#v0.6.2
```
```text
https://github.com/FRZ5201314/UnityEditorMCP.git?path=/Packages/com.yys.unity-mcp-bridge#v0.6.2
```
After importing, open in Unity menu:
```text
Tools > Unity MCP
```
### 2. Configure MCP Server
MCP Server is released as an npm package, recommended to start with `npx`:
```json
{
"type": "stdio",
"command": "npx",
"args": ["-y", "@luoluo123/unity-mcp-server@0.6.2"],
"env": {
"UNITY_MCP_AUTO_DETECT": "true",
"UNITY_MCP_DETECT_HOST": "127.0.0.1",
"UNITY_MCP_DETECT_PORT_START": "8765",
"UNITY_MCP_DETECT_PORT_END": "8775",
"UNITY_MCP_TIMEOUT_MS": "30000"
},
"enabled": true
}
```
### 3. Verify Connection
Call after starting Unity Editor and MCP client:
```text
unity_health
```
Return Bridge status information to confirm connection.
## 🧩 Project Structure
```text
Packages/com.yys.unity-mcp-bridge/ Unity Editor Bridge UPM package
server/ Node.js MCP stdio server
docs/ Usage instructions, test records, and implementation documents
```
## 🧭 Multiple Projects
When multiple Unity projects are opened simultaneously, each Bridge will automatically occupy an available port in `8765-8775`. MCP Server selection priority:
1. `UNITY_MCP_BRIDGE_URL`
2. `UNITY_MCP_PROJECT_PATH`
3. `UNITY_MCP_PROJECT_NAME`
4. Current working directory inference
5. Unique online Bridge
6. Manual selection via `unity_bridge_list` / `unity_bridge_select` when multiple candidates
## 🔐 Permissions and Logs
Bridge logs:
```text
Library/UnityMcp/bridge.log
```
Switch in `Tools > Unity MCP`:
- `Allow Scene Object Delete`
- `Allow Asset Delete`
- `Allow Script Write`
These switches only restrict MCP Bridge exposed command entries, not Codex, Shell, Unity UI, or file system-level global security boundaries.
## 🛠 Common Tools
- `unity_health`
- `unity_bridge_list`
- `unity_bridge_select`
- `unity_project_get_info`
- `unity_hierarchy_list`
- `unity_gameobject_create`
- `unity_transform_set`
- `unity_component_add`
- `unity_asset_find`
- `unity_prefab_create`
- `unity_script_create`
- `unity_script_attach`
See complete tools and parameters in [Complete Usage Guide](docs/mcp-usage-guide.md).
## 📚 Documentation
- [Complete Usage Guide](docs/mcp-usage-guide.md)
- [Development Status](docs/development-status.md)
- [Implementation Plan](docs/implementation-plan.md)
