# unity_mcp_server

**Repository Path**: weyson_admin/unity_mcp_server

## Basic Information

- **Project Name**: unity_mcp_server
- **Description**: unity mcp server
- **Primary Language**: C#
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-12
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Unity MCP Server

Unity MCP Server is an open-source project designed to connect the Unity Editor with the Model Context Protocol (MCP). It enables external tools (such as Cursor, Claude Desktop, etc.) to communicate with the Unity Editor via the MCP protocol, enabling functionalities like scene management, GameObject manipulation, and script execution.

## Features

- **Unity Connection Management** - Automatically discover and connect to local Unity Editor instances
- **Scene and Hierarchy Management** - Create, open, and save scenes; manage GameObject hierarchy structures
- **GameObject Operations** - Create, delete, find, and modify GameObjects and their components
- **Script Execution** - Execute C# scripts within the Unity Editor
- **Asset Management** - Load, create, and find project assets
- **Editor State Control** - Play, pause, stop the editor, and perform other editor operations
- **Batch Command Execution** - Support for executing multiple commands in a single request

## System Requirements

- Unity Editor (2020.3 or later)
- Python 3.10+
- An active Unity project (must include UnityBridge)

## Quick Start

### 1. Install Dependencies

```bash
cd Server
pip install -e .
```

### 2. Set Environment Variables

```bash
# Set the Unity project path (optional)
export UNITY_PROJECT_PATH=/path/to/your/unity/project

# Set log level (optional, default: INFO)
export UNITY_MCP_VERBOSE=true
```

### 3. Verify Unity Connection

Ensure the Unity Editor is open and the project is loaded. Run the diagnostic command:

```bash
python -m unity_mcp_server diagnose
```

### 4. Start the MCP Server

Stdio mode (for Cursor, Claude Desktop, etc.):

```bash
python -m unity_mcp_server
```

## Cursor Configuration Example

Add the following to Cursor’s MCP configuration file:

```json
{
  "mcpServers": {
    "unity": {
      "command": "python",
      "args": ["-m", "unity_mcp_server"],
      "env": {
        "UNITY_PROJECT_PATH": "/path/to/your/project"
      }
    }
  }
}
```

## Available MCP Tools

| Tool Name | Description |
|----------|-------------|
| `manage_scene` | Scene management (create, open, save) |
| `manage_gameobject` | GameObject operations (create, delete, find) |
| `manage_script` | Script management (execute, create) |
| `manage_asset` | Asset management (load, find) |
| `manage_editor` | Editor control (play, pause, stop) |
| `manage_screenshot` | Screenshot management |

## Architecture

```
┌─────────────┐     MCP      ┌──────────────────┐    Bridge     ┌─────────────┐
│  External   │ ──────────→ │  Unity MCP Server │ ──────────→ │ Unity Editor │
│   Tools     │             │   (Python)        │              │   (C#)      │
│ (e.g., Cursor)│           └──────────────────┘              └─────────────┘
└─────────────┘
```

- **MCP Server (Python)** - Handles MCP protocol processing and tool mapping
- **Bridge Protocol** - A custom protocol for communication between Python and Unity C#
- **Unity Editor (C#)** - The Unity-side Bridge plugin that receives and executes commands

## Development

### Run Tests

```bash
cd Server
python run_tests.py
```

### Project Structure

```
Server/
├── src/unity_mcp_server/
│   ├── __main__.py          # Entry point
│   ├── server.py            # MCP server implementation
│   ├── config.py            # Configuration management
│   ├── bridge/
│   │   ├── client.py        # Unity Bridge client
│   │   ├── discovery.py     # Unity instance discovery
│   │   └── protocol.py      # Protocol encoding/decoding
│   └── tools/
│       ├── definitions.py  # Tool definitions
│       └── unity_docs.py    # Unity documentation retrieval
└── tests/                   # Test files
```

## License

MIT License