How to Manage Build Settings with Unity MCP: A Complete Guide

Unity MCP exposes build configuration through the ManageBuild tool, allowing AI assistants and automation scripts to programmatically read or modify Unity Editor build settings via JSON commands sent over the Model Context Protocol.

The CoplayDev/unity-mcp repository provides a bridge between AI assistants and the Unity Editor, enabling programmatic control over build configurations without manual GUI interaction. By leveraging the ManageBuild MCP tool, developers can automate build pipeline preparation, switch target platforms, and adjust player settings from Python scripts or AI agents. This integration centralizes build management through a standardized protocol that works across Unity 2021-2026 versions.

Understanding the ManageBuild Architecture

Unity Editor Implementation

In MCPForUnity/Editor/Tools/ManageBuild.cs, the tool is decorated with the [McpForUnityTool] attribute, enabling automatic discovery by the CommandRegistry when the Unity Editor loads. The HandleCommand method receives a JSON payload containing action, setting, and optional value parameters, parsing them through the ToolParams helper before delegating to BuildSettingsHelper.

Build Settings Helper Layer

The BuildSettingsHelper class in MCPForUnity/Editor/Tools/Build/BuildSettingsHelper.cs serves as the abstraction layer over Unity's native PlayerSettings and EditorUserBuildSettings APIs. This helper centralizes version-compatibility shims, mapping string setting names like "development" or "outputPath" to their corresponding Unity API calls, ensuring consistent behavior across different Unity versions.

Python Server Bridge

On the client side, Server/src/services/tools/manage_build.py mirrors the Unity tool's interface, exposing the same parameters to MCP clients. When invoked, it serializes the request and transmits it to the Unity Editor via the MCP bridge (WebSocket or Stdio), routing through CommandRegistry.InvokeCommandAsync("manage_build", params).

Supported Build Settings and Parameters

The ManageBuild tool supports standard Unity build parameters including:

• development: Boolean flag for development builds
• outputPath: String path for build artifacts
• targetPlatform: Build target (Android, iOS, WebGL, StandaloneWindows, etc.)
• scriptingBackend: Mono vs IL2CPP selection
• architecture: ARM64, x86_64, etc.

Practical Code Examples

Enable Development Build from Python

from services.registry import mcp_for_unity_tool

async def configure_development_build(ctx):
    params = {
        "action": "set",
        "setting": "development",
        "value": True
    }
    response = await ctx.call_mcp_tool("manage_build", params)
    print(response)  # Returns: {"status":"ok","message":"Set development = True"}

This invokes BuildSettingsHelper.SetBool("development", true) inside the Unity Editor.

Retrieve Current Build Output Path

// Example from test suite in ManageBuildTests.cs
[Test]
public void GetOutputPath_ReturnsValidPath()
{
    var result = ManageBuild.HandleCommand(
        JObject.FromObject(new { action = "get", setting = "outputPath" })
    );
    
    var json = JObject.FromObject(result);
    Assert.IsTrue(json["value"].Value<string>().Contains("Builds"));
}

The test validates that BuildSettingsHelper.GetString("outputPath") returns the active build directory.

Switch Target Platform via CLI

python -m mcp_cli manage_build --action set --setting targetPlatform --value Android

This command translates to EditorUserBuildSettings.activeBuildTarget = BuildTarget.Android inside the Unity Editor via BuildSettingsHelper.SetTargetPlatform().

Automated Build Configuration in CI

import asyncio
from unity_mcp_client import UnityMCP

async def prepare_build_environment():
    client = UnityMCP()
    
    # Configure build settings

    await client.call_tool("manage_build", {
        "action": "set",
        "setting": "scriptingBackend",
        "value": "IL2CPP"
    })
    
    await client.call_tool("manage_build", {
        "action": "set", 
        "setting": "architecture",
        "value": "ARM64"
    })
    
    # Verify configuration

    config = await client.call_tool("manage_build", {
        "action": "get",
        "setting": "development"
    })
    
    return config

Integration with BuildRunner

While ManageBuild configures settings, MCPForUnity/Editor/Tools/Build/BuildRunner.cs executes the actual build process using these configurations. The separation of concerns allows you to first validate settings via ManageBuild, then trigger compilation through the BuildRunner tool or Unity's BuildPipeline.BuildPlayer method.

Summary

• ManageBuild is the primary MCP tool for build configuration, registered in ManageBuild.cs with the [McpForUnityTool] attribute.
• BuildSettingsHelper.cs abstracts Unity's native APIs, providing version-safe wrappers for PlayerSettings and EditorUserBuildSettings.
• Parameters use a standard JSON schema with action ("get" or "set"), setting name, and optional value.
• The Python implementation in manage_build.py exposes identical functionality to MCP clients, enabling cross-platform automation.
• Unit tests in ManageBuildTests.cs validate get/set operations, ensuring reliability for CI/CD pipelines.

Frequently Asked Questions

What Unity versions are supported for managing build settings?

The BuildSettingsHelper class includes compatibility shims for Unity 2021 through 2026, handling API changes in PlayerSettings and EditorUserBuildSettings transparently. As long as your Unity Editor version falls within this range, the MCP tool will map settings correctly without requiring version-specific code.

Can I modify build settings while Unity is in Play mode?

While the ManageBuild tool can accept commands during Play mode, many PlayerSettings changes require the Editor to be in Edit mode and may trigger a domain reload. For best results, execute build setting modifications before entering Play mode or use the tool exclusively in automated Headless/CI environments where the Editor remains in Edit mode.

How does ManageBuild differ from the BuildRunner tool?

ManageBuild specifically handles configuration and inspection of build settings (getting/setting PlayerSettings), while BuildRunner executes the actual compilation and packaging process defined in BuildRunner.cs. Typically, you use ManageBuild to configure the environment, then invoke BuildRunner or BuildPipeline.BuildPlayer to generate the final artifacts.

Is it possible to set custom build settings not listed in the standard parameters?

The BuildSettingsHelper implements a mapping layer for common settings, but you can extend it by modifying BuildSettingsHelper.cs to handle additional PlayerSettings properties. The system uses reflection-based fallbacks for unsupported settings, though explicit mapping provides better type safety and error handling.

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