# coplaydev/unity-mcp architecture

> Architecture diagram of the GitHub repository coplaydev/unity-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coplaydev/unity-mcp
- Repository: https://github.com/coplaydev/unity-mcp

## Overview

##### Project type and purpose
- Unity MCP is a two‐component, local “bridge” system that lets LLM-based MCP Clients (e.g. Claude Desktop, Cursor, VSCode Copilot) drive the Unity Editor.
- It consists of:
- UnityMcpBridge – a Unity Package (C#) loaded into the Editor (Editor + Runtime code)
- UnityMcpServer – a Python 3.12 microservice (uv-driven) that relays MCP calls

##### File structure
- Top-level directories:
- UnityMcpBridge/ – contains the Unity Package, split into:
– Editor/ (Data, Helpers, Models, Tools, Windows, asmdef files)
– Runtime/ (Serialization converters, asmdef)
- UnityMcpServer/src/ – Python service, with server.py, port_discovery.py, config.py, pyproject.toml, uv.lock, plus a tools/ subpackage that mirrors the Bridge’s tool commands
- Other files: Dockerfile (server containerization), deploy-dev.bat & restore-dev.bat (deployment scripts)

##### README for additional insights
[Your LLM via MCP Client] ↔ [Unity MCP Server (Python)] ↔ [Unity MCP Bridge (Unity Editor)]
- Lists supported tools (manage_asset, manage_scene, manage_script, etc.) and setup steps (auto-configure vs manual)
- Emphasizes JSON-RPC over a local port, uv CLI invocation, and asmdef based plugin

##### Elements
- Python server (green gears)
- Unity Bridge (blue cube)
- External client (yellow cloud or terminal)
- Unity Editor (gray application window)

##### Detail to capture
- The Editor vs Runtime boundary within the Bridge package
- Port discovery and server startup flow (port_discovery.py → server.py)
- How “Auto-Configure” writes to the MCP Client’s config file vs Manual Configuration snippets
- The round-trip of commands: MCP Client → Python Server → Bridge → UnityEditor API → Bridge → Server → Client

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External MCP Client
    subgraph "External MCP Client" 
        direction TB
        MCPClient["LLM via MCP Client"]:::client
    end

    %% Python Server Layer
    subgraph "UnityMcpServer (Python Service)" 
        direction TB
        PortDiscovery["Port Discovery"]:::python
        Server["server.py"]:::python
        ConfigLoader["config.py"]:::python
        subgraph "Tools Handlers"
            direction TB
            ExecMenu["execute_menu_item.py"]:::python
            ManageAsset["manage_asset.py"]:::python
            ManageEditor["manage_editor.py"]:::python
            ManageGameObject["manage_gameobject.py"]:::python
            ManageScene["manage_scene.py"]:::python
            ManageScript["manage_script.py"]:::python
            ManageShader["manage_shader.py"]:::python
            ReadConsole["read_console.py"]:::python
        end
        UnityConn["unity_connection.py"]:::python
        CLIManifest["pyproject.toml\nuv.lock"]:::python
        Dockerfile["Dockerfile"]:::python
    end

    %% Unity Bridge + Editor Layer
    subgraph "UnityMcpBridge (Unity Package)" 
        direction TB
        PackageManifest["package.json"]:::unitybridge
        subgraph "Editor Module"
            direction TB
            Data["DefaultServerConfig.cs"]:::unitybridge
            Helpers["PortManager.cs"]:::unitybridge
            Models["Models"]:::unitybridge
            ToolsCS["CommandRegistry.cs"]:::unitybridge
            Windows["ManualConfigEditorWindow.cs"]:::unitybridge
            EditorAsmdef["UnityMcpBridge.Editor.asmdef"]:::unitybridge
        end
        subgraph "Runtime Module"
            direction TB
            Serialization["UnityTypeConverters.cs"]:::unitybridge
            RuntimeAsmdef["UnityMcpBridge.Runtime.asmdef"]:::unitybridge
        end
    end

    %% Unity Editor Host
    UnityEditor["Unity Editor\n(UnityEditor API)"]:::unityeditor

    %% Connections
    MCPClient -->|"uv CLI"| PortDiscovery
    PortDiscovery -->|"discovers port"| Server
    MCPClient -->|"uv CLI"| Server
    Server -->|"dispatch JSON-RPC"| ExecMenu
    Server --> ManageAsset
    Server --> ManageEditor
    Server --> ManageGameObject
    Server --> ManageScene
    Server --> ManageScript
    Server --> ManageShader
    Server --> ReadConsole
    Server -->|"handles config"| ConfigLoader
    MCPClient -->|"uses CLI manifest"| CLIManifest
    Server -->|"containerized by"| Dockerfile

    Server <-->|"WebSocket/HTTP JSON-RPC"| Data
    Data --> Helpers
    Helpers --> ToolsCS
    ToolsCS -->|"invokes"| UnityEditor
    UnityEditor -->|"returns results"| ToolsCS
    ToolsCS --> Data

    PackageManifest -.-> EditorAsmdef
    PackageManifest -.-> RuntimeAsmdef

    %% Click Events
    click Data "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpBridge/Editor/Data/DefaultServerConfig.cs"
    click Helpers "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpBridge/Editor/Helpers/PortManager.cs"
    click Models "https://github.com/coplaydev/unity-mcp/tree/main/UnityMcpBridge/Editor/Models/"
    click ToolsCS "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpBridge/Editor/Tools/CommandRegistry.cs"
    click Windows "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpBridge/Editor/Windows/ManualConfigEditorWindow.cs"
    click EditorAsmdef "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpBridge/Editor/UnityMcpBridge.Editor.asmdef"
    click Serialization "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpBridge/Runtime/Serialization/UnityTypeConverters.cs"
    click RuntimeAsmdef "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpBridge/Runtime/UnityMcpBridge.Runtime.asmdef"
    click PackageManifest "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpBridge/package.json"
    click Server "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpServer/src/server.py"
    click PortDiscovery "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpServer/src/port_discovery.py"
    click ConfigLoader "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpServer/src/config.py"
    click CLIManifest "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpServer/src/pyproject.toml"
    click CLIManifest "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpServer/src/uv.lock"
    click Dockerfile "https://github.com/coplaydev/unity-mcp/tree/main/UnityMcpServer/src/Dockerfile"
    click ExecMenu "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpServer/src/tools/execute_menu_item.py"
    click ManageAsset "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpServer/src/tools/manage_asset.py"
    click ManageEditor "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpServer/src/tools/manage_editor.py"
    click ManageGameObject "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpServer/src/tools/manage_gameobject.py"
    click ManageScene "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpServer/src/tools/manage_scene.py"
    click ManageScript "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpServer/src/tools/manage_script.py"
    click ManageShader "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpServer/src/tools/manage_shader.py"
    click ReadConsole "https://github.com/coplaydev/unity-mcp/blob/main/UnityMcpServer/src/tools/read_console.py"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef python fill:#afa,stroke:#070,stroke-width:1px
    classDef unitybridge fill:#bbf,stroke:#00f,stroke-width:1px
    classDef unityeditor fill:#eee,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5
```
