|
1 | | -# Unity-MCP Pro — Agentic Unity Bridge |
2 | | -**Connects LLMs (Claude, GPT) to Unity in real-time via MCP Protocol** |
| 1 | +# 🌌 Unity-MCP Pro: The Agentic Unity Bridge |
3 | 2 |
|
| 3 | +[](https://github.com/NishantJLU/Unity-MCP/releases) |
| 4 | +[](https://github.com/NishantJLU/Unity-MCP) |
4 | 5 | [](https://github.com/NishantJLU/Unity-MCP/actions) |
5 | 6 | [](https://github.com/NishantJLU/Unity-MCP/actions) |
6 | | - |
| 7 | +[](https://opensource.org/licenses/MIT) |
7 | 8 |
|
8 | | -## 🏗️ How It Works |
9 | | -The bridge facilitates bidirectional communication between Large Language Models and the Unity Engine. |
| 9 | +**Unity-MCP Pro** is a high-performance bridge that transforms the Unity Editor into an agentic environment. It enables LLMs (like Claude 3.5 Sonnet and Gemini 1.5 Pro) to interact with Unity in real-time for AI-driven level design, scene auditing, and live construction. |
10 | 10 |
|
11 | | -```text |
12 | | -LLM (Claude/GPT) ──▶ MCP Server (Node.js) ──▶ WebSocket/HTTP ──▶ Unity (C# Bridge) |
13 | | - ▲ │ |
14 | | - └───────────────────────────────────────────────────────────┘ |
15 | | - World State & Feedback |
| 11 | +--- |
| 12 | + |
| 13 | +## 🚀 Quick Start (3-Minute Setup) |
| 14 | + |
| 15 | +### 1. Download & Install |
| 16 | +Download the **[Latest Release (v1.0.0)](https://github.com/NishantJLU/Unity-MCP/releases/latest)** and extract it. Double-click **`setup.bat`** to install dependencies automatically. |
| 17 | + |
| 18 | +### 2. Add to Unity |
| 19 | +Drag the `UnityScripts` folder into your Unity project's `Assets` folder. Open **Window > AI > Unity MCP Pro** and click **ESTABLISH LINK**. |
| 20 | + |
| 21 | +### 3. Connect to AI |
| 22 | +Add this snippet to your `claude_desktop_config.json`: |
| 23 | +```json |
| 24 | +{ |
| 25 | + "mcpServers": { |
| 26 | + "unity-mcp-pro": { |
| 27 | + "command": "node", |
| 28 | + "args": ["C:/PATH/TO/Unity-MCP/unity-mcp-server/index.js"] |
| 29 | + } |
| 30 | + } |
| 31 | +} |
16 | 32 | ``` |
17 | 33 |
|
18 | | -## 🛠️ Prerequisites |
19 | | -- **Node.js**: 18.x or higher |
20 | | -- **Unity Engine**: 2021.3 LTS or higher |
21 | | -- **LLM API Key**: OpenAI or Anthropic key for the MCP client |
| 34 | +--- |
| 35 | + |
| 36 | +## ❓ Why Unity-MCP Pro? |
| 37 | +While basic scripts can move objects, **Unity-MCP Pro** provides a deep, production-grade integration: |
| 38 | +* **👁️ AI Vision:** AI can "see" through your Editor camera to reason about layout and aesthetics. |
| 39 | +* **⚡ Reflection-Based:** No need to write new tools. AI can access *any* public variable on *any* component via C# Reflection. |
| 40 | +* **🛡️ Safety First:** All commands are dispatched via the Main Thread to prevent Editor crashes. |
| 41 | +* **📊 Full Context:** AI receives a high-fidelity JSON map of your scene hierarchy, tags, and layers. |
| 42 | + |
| 43 | +--- |
| 44 | + |
| 45 | +## 💎 Pro Features |
| 46 | + |
| 47 | +### AI Vision (Visual Feedback) |
| 48 | +Empower your AI to capture live snapshots of the Editor, allowing it to reason about material properties, lighting, and UI placement visually. |
| 49 | + |
| 50 | +### Scene Graph Analytics |
| 51 | +The AI receives a structured map of the entire scene hierarchy, enabling complex architectural reasoning and automated auditing. |
| 52 | + |
| 53 | +### Reflection-Based Control |
| 54 | +Modify deep parameters like Light intensity, Rigidbody mass, or custom script variables without needing pre-defined tools. |
| 55 | + |
| 56 | +--- |
22 | 57 |
|
23 | | -## 🚀 Setup Guide |
| 58 | +## 🏗️ Technical Architecture |
24 | 59 |
|
25 | | -### 1. Node.js MCP Server |
26 | | -1. Navigate to the `server/` directory. |
27 | | -2. Run `npm install`. |
28 | | -3. Build the server: `npm run build`. |
29 | | -4. Configure your MCP client (e.g., Claude Desktop) to use the built `index.js`. |
| 60 | +- **The Brain (Node.js):** An MCP server that exposes Unity functionality as structured tools. |
| 61 | +- **The Hand (C#):** A custom Editor window with a high-performance HTTP listener. |
| 62 | +- **Communication:** Low-latency JSON bridge for real-time AI command execution. |
30 | 63 |
|
31 | | -### 2. Unity Bridge |
32 | | -1. Open your Unity project. |
33 | | -2. Install the package via UPM: `https://github.com/NishantJLU/Unity-MCP.git?path=/unity`. |
34 | | -3. Open the bridge window: **Window > AI > Game Master Bridge**. |
35 | | -4. Click **Start Bridge**. |
| 64 | +--- |
36 | 65 |
|
37 | | -## 🎮 Use Cases |
38 | | -- **AI-Driven NPC Behavior**: Generate dynamic dialogue and actions based on world state. |
39 | | -- **Procedural Level Generation**: Use natural language to describe and spawn complex environments. |
40 | | -- **Game Testing Automation**: Instruct an AI agent to "find bugs" or "playtest level 1" via the bridge. |
| 66 | +## 💬 Community & Feedback |
| 67 | +* **Discussion:** Have an idea for a new tool? [Join the Discussion](https://github.com/NishantJLU/Unity-MCP/discussions). |
| 68 | +* **Bugs:** Report issues [here](https://github.com/NishantJLU/Unity-MCP/issues). |
| 69 | +* **Support:** If this helps your workflow, please consider giving us a ⭐! |
41 | 70 |
|
42 | | -## 📜 License |
43 | | -This project is licensed under the MIT License. |
| 71 | +--- |
| 72 | +**Developed by [NishantJLU](https://github.com/NishantJLU)** |
0 commit comments