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

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. 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:

cd Server
uv run python src/main.py

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

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 or 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:

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 and 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 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. 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:

[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 – Validates and extracts JSON parameters from incoming requests
• 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 starts the FastMCP server and handles transport initialization

• Unity bootstrap: 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 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, while the Unity-side WebSocket client is managed by 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 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 to run headless Unity tests across the bridge.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}