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

> Master Unity MCP build settings management. Learn to programmatically read and modify Unity Editor build settings using JSON commands over Model Context Protocol. Automate your builds efficiently.

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

---

**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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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

```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

```csharp
// 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

```bash
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

```python
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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/manage_build.py) exposes identical functionality to MCP clients, enabling cross-platform automation.
- Unit tests in [`ManageBuildTests.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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.