# Where to Find the Main Source Files in Unity MCP: A Complete Guide

> Locate Unity MCP main source files easily. Discover Python server code in Server/src/ and Unity Editor package in MCPForUnity/. Your complete guide awaits.

- Repository: [Coplay/unity-mcp](https://github.com/CoplayDev/unity-mcp)
- Tags: how-to-guide
- Published: 2026-07-07

---

**The main source files in Unity MCP are located in two distinct directories: the Python server code lives in `Server/src/` and the Unity Editor package resides in `MCPForUnity/`.**

Unity MCP implements the Model Context Protocol (MCP) as a bridge between AI assistants and the Unity Editor through a dual-codebase architecture. Understanding where to find the main source files is essential for extending the protocol, debugging tool implementations, or contributing new features. This guide maps the repository structure based on the actual CoplayDev/unity-mcp source code.

## Python Server Source Files (`Server/`)

The Python side of Unity MCP handles MCP protocol compliance, tool discovery, and transport layer management. This codebase is located in the `Server/` directory and uses FastMCP for server functionality.

### Entry Point and Server Bootstrap

The primary entry point for the Python server is **[`Server/src/main.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/main.py)**. This file initializes the FastMCP server, loads available tools, registers CLI commands, and opens the HTTP/StdIO bridge for communication.

When running the server locally, you launch this file directly:

```bash
cd Server
uv run python src/main.py

```

For development with hot reload, use the FastAPI server mode:

```bash
uv run python -m uvicorn src.main:app --reload

```

### Tools and Services

Tool implementations are organized under **`Server/src/services/tools/`**. Each Python tool file (such as [`manage_material.py`](https://github.com/CoplayDev/unity-mcp/blob/main/manage_material.py) or [`manage_gameobject.py`](https://github.com/CoplayDev/unity-mcp/blob/main/manage_gameobject.py)) contains functions decorated with `@mcp_for_unity_tool` that define the tool's schema and behavior.

These tools forward requests to Unity via the `send_with_unity_instance` function. For example, a material management tool appears as:

```python
from services.registry import mcp_for_unity_tool

@mcp_for_unity_tool(
    description="Create a new Unity material.",
    group="core",
)
async def manage_material(
    ctx,
    action: Literal["create", "delete"],
    name: str,
) -> dict:
    unity = await get_unity_instance_from_context(ctx)
    params = {"action": action, "name": name}
    return await send_with_unity_instance(
        async_send_command_with_retry,
        unity,
        "manage_material",
        params,
    )

```

### Transport Layer

The transport implementation resides in **`Server/src/transport/`**. Key files include [`plugin_hub.py`](https://github.com/CoplayDev/unity-mcp/blob/main/plugin_hub.py) and [`unity_transport.py`](https://github.com/CoplayDev/unity-mcp/blob/main/unity_transport.py), which handle StdIO, HTTP, and WebSocket communication between the Python server and the Unity Editor instance.

### CLI Commands

Developer-facing command-line tools are located in **`Server/src/cli/`**. The entry point **[`Server/src/cli/main.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/cli/main.py)** implements the `mcp` command-line tool for advanced server management and debugging operations.

## Unity Editor Package Source Files (`MCPForUnity/`)

The Unity side of the bridge is implemented as a UPM (Unity Package Manager) package in the `MCPForUnity/` directory. This C# codebase executes actual Unity API calls on behalf of the Python server.

### Bootstrap and Initialization

The Unity-side entry point is **[`MCPForUnity/Editor/McpCiBoot.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/McpCiBoot.cs)**. This bootstrap file creates the WebSocket hub, initializes the communication bridge, and registers all `[McpForUnityTool]` and `[McpForUnityResource]` implementations when the Unity Editor loads.

After installing the `MCPForUnity` package, the editor automatically starts the WebSocket hub when a client connects—no additional startup code is required.

### Tool Implementations

C# tool implementations mirror their Python counterparts in **`MCPForUnity/Editor/Tools/`**. Each tool class is marked with the `[McpForUnityTool]` attribute and implements a static `HandleCommand(JObject @params)` method.

The C# implementation corresponding to the Python material tool above appears in **[`MCPForUnity/Editor/Tools/ManageMaterial.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Tools/ManageMaterial.cs)**:

```csharp
[McpForUnityTool("manage_material", Group = "core")]
public static class ManageMaterial
{
    public static object HandleCommand(JObject @params)
    {
        var p = new ToolParams(@params);
        var action = p.RequireString("action");
        var name   = p.RequireString("name");

        if (action == "create")
        {
            var mat = new Material(Shader.Find("Standard")) { name = name };
            AssetDatabase.CreateAsset(mat, $"Assets/{name}.mat");
            return new SuccessResponse("Material created.", new { name });
        }

        return new SuccessResponse("Done.");
    }
}

```

### Helpers and Compatibility

Utility classes for parameter parsing and version compatibility are located in **`MCPForUnity/Editor/Helpers/`** and **`MCPForUnity/Runtime/`**. Key files include:

- **[`ToolParams.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/ToolParams.cs)** – Validates and extracts JSON parameters from incoming requests
- **[`UnityCompatShims.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/UnityCompatShims.cs)** – Provides Unity version-specific API compatibility shims

## How the Two Sides Communicate

The Python server and Unity Editor package are loosely coupled through the transport layer. The Python side in `Server/src/transport/` only knows the shape of each command (name plus JSON parameters), while the Unity side in `MCPForUnity/Editor/` executes the actual Unity API calls.

When implementing new tools, you must add corresponding files in both **`Server/src/services/tools/`** (Python) and **`MCPForUnity/Editor/Tools/`** (C#) to maintain symmetry across the bridge.

## Summary

- **Python server entry**: [`Server/src/main.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/main.py) starts the FastMCP server and handles transport initialization
- **Unity bootstrap**: [`MCPForUnity/Editor/McpCiBoot.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/McpCiBoot.cs) initializes the WebSocket hub and registers tools
- **Python tools**: Located in `Server/src/services/tools/` using `@mcp_for_unity_tool` decorators
- **C# tools**: Located in `MCPForUnity/Editor/Tools/` using `[McpForUnityTool]` attributes

- **Transport layer**: `Server/src/transport/` contains WebSocket and StdIO communication code
- **CLI tools**: `Server/src/cli/` provides developer command-line utilities
- **Test harness**: [`tools/local_harness.py`](https://github.com/CoplayDev/unity-mcp/blob/main/tools/local_harness.py) runs headless Unity tests across the bridge

## Frequently Asked Questions

### What is the difference between the Server and MCPForUnity directories?

The `Server/` directory contains Python code that implements the MCP protocol and communicates with AI assistants, while `MCPForUnity/` contains the C# Unity Editor package that executes actual Unity API commands. The Python server sends JSON commands via WebSocket, and the Unity package processes them and returns results.

### How do I add a new tool to Unity MCP?

You must create two files: one in `Server/src/services/tools/` with the Python `@mcp_for_unity_tool` decorator, and one in `MCPForUnity/Editor/Tools/` with the C# `[McpForUnityTool]` attribute. Both must share the same tool name string and compatible parameter schemas so they can communicate across the bridge.

### Where is the WebSocket communication handled?

The Python-side WebSocket hub is implemented in [`Server/src/transport/plugin_hub.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/plugin_hub.py), while the Unity-side WebSocket client is managed by [`MCPForUnity/Editor/McpCiBoot.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/McpCiBoot.cs). These files coordinate the bidirectional communication between the AI assistant and the Unity Editor.

### Can I run the Python server without opening Unity?

Yes, you can run [`Server/src/main.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/main.py) independently, but tool calls will fail unless the Unity Editor is running with the `MCPForUnity` package installed and the WebSocket connection established. For testing without the full Unity GUI, you can use [`tools/local_harness.py`](https://github.com/CoplayDev/unity-mcp/blob/main/tools/local_harness.py) to run headless Unity tests across the bridge.