### Configure MCP Server with CLI Arguments

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/REMOTE_SERVER_AUTH.md

Example of starting the MCP server with HTTP transport and API key authentication enabled using command-line arguments.

```bash
python -m src.main \
  --transport http \
  --http-host 0.0.0.0 \
  --http-port 8080 \
  --http-remote-hosted \
  --api-key-validation-url https://auth.example.com/api/validate-key \
  --api-key-login-url https://app.example.com/api-keys \
  --api-key-cache-ttl 120
```

--------------------------------

### Configure MCP Server with Environment Variables

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/REMOTE_SERVER_AUTH.md

Example of starting the MCP server with HTTP transport and API key authentication enabled using environment variables.

```bash
export UNITY_MCP_TRANSPORT=http
export UNITY_MCP_HTTP_HOST=0.0.0.0
export UNITY_MCP_HTTP_PORT=8080
export UNITY_MCP_HTTP_REMOTE_HOSTED=true
export UNITY_MCP_API_KEY_VALIDATION_URL=https://auth.example.com/api/validate-key
export UNITY_MCP_API_KEY_LOGIN_URL=https://app.example.com/api-keys

python -m src.main
```

--------------------------------

### Run MCP Server Manually

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/CLI_EXAMPLE.md

Example command to manually start the MCP HTTP server on macOS using uvx. Ensure the path to unity-mcp is correct.

```bash
/opt/homebrew/bin/uvx --no-cache --refresh --from /XXX/unity-mcp/Server mcp-for-unity --transport http --http-url http://localhost:8080
```

--------------------------------

### Install Unity Package and Verify

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

Install the Unity Input System package and verify its installation by checking for compilation errors and package information. Poll job status until completion.

```python
manage_packages(action="ping")
```

```python
manage_packages(action="list_packages")
```

```python
manage_packages(action="status", job_id="<job_id>")
```

```python
manage_packages(action="add_package", package="com.unity.inputsystem")
```

```python
manage_packages(action="status", job_id="<job_id>")
```

```python
read_console(types=["error"], count=10)
```

```python
manage_packages(action="get_package_info", package="com.unity.inputsystem")
```

--------------------------------

### Install uv on Windows

Source: https://github.com/coplaydev/unity-mcp/wiki/3.-Common-Setup-Problems

Use PowerShell to download and execute the installation script for uv, a required dependency for the MCP server.

```powershell
irm https://astral.sh/uv/install.ps1 | iex
```

--------------------------------

### Argument Order Examples

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Examples demonstrating the required order for arguments in specific commands like 'material assign', 'prefab create', and 'component set'. Always refer to --help for precise syntax.

```bash
material assign MATERIAL_PATH TARGET
prefab create TARGET PATH
component set TARGET COMPONENT PROPERTY VALUE
```

--------------------------------

### Install Unity MCP CLI

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/CLI_EXAMPLE.md

Install Unity MCP using pip or uv. Navigate to the 'Server' directory within the unity-mcp repository before running the installation command.

```bash
cd Server  # In unity-mcp repo
pip install -e .
# Or with uv:
uv pip install -e .
```

--------------------------------

### Unity MCP CLI Quick Start Commands

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Execute basic Unity MCP CLI commands to interact with the Unity editor, such as getting scene hierarchy, creating game objects, modifying them, taking screenshots, and entering play mode.

```bash
# Get scene hierarchy
unity-mcp scene hierarchy

# Create a cube
unity-mcp gameobject create "MyCube" --primitive Cube

# Move the cube
unity-mcp gameobject modify "MyCube" --position 0 2 0

# Take a screenshot
unity-mcp camera screenshot

# Enter play mode
unity-mcp editor play
```

--------------------------------

### Install Unity MCP CLI

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/CLI_USAGE.md

Install the Unity MCP CLI package. Use 'pip' or 'uv' for installation.

```bash
cd Server
pip install -e .
# Or with uv:
uv pip install -e .
```

--------------------------------

### Install Unity MCP CLI with uv tool

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Install or run the Unity MCP CLI using the uv tool. This allows running commands directly without a full installation or installing it as a tool.

```bash
# Run directly without installing
uvx --from /path/to/unity-mcp/Server unity-mcp --help

# Or install as a tool
uv tool install /path/to/unity-mcp/Server
```

--------------------------------

### Install MCP for Unity Beta from Git URL

Source: https://github.com/coplaydev/unity-mcp/blob/beta/README.md

Use this Git URL in Unity's Package Manager to install the beta branch of the MCP for Unity package for the latest features.

```text
https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#beta
```

--------------------------------

### Install Claude CLI using Native Installer

Source: https://github.com/coplaydev/unity-mcp/wiki/3.-Common-Setup-Problems

Download and execute the native installer script for Claude CLI. This method places the binary in a stable system path.

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

--------------------------------

### Install uv on Windows PowerShell

Source: https://github.com/coplaydev/unity-mcp/wiki/1.-Fix-Unity-MCP-and-Cursor,-VSCode,-Windsurf,-Rider

Install uv using PowerShell with either the provided script or winget.

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# or
winget install --id=astral-sh.uv -e
```

--------------------------------

### Example Prompt: Create Cubes

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/i18n/README-zh.md

An example prompt to demonstrate creating basic geometric shapes in Unity using natural language commands through MCP.

```text
Create a red, blue and yellow cube
```

--------------------------------

### Install uv on macOS/Linux/WSL

Source: https://github.com/coplaydev/unity-mcp/wiki/1.-Fix-Unity-MCP-and-Cursor,-VSCode,-Windsurf,-Rider

Install uv using the provided curl script or Homebrew on macOS.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
# or Homebrew on macOS
brew install uv
```

--------------------------------

### Install Python on Windows

Source: https://github.com/coplaydev/unity-mcp/wiki/1.-Fix-Unity-MCP-and-Cursor,-VSCode,-Windsurf,-Rider

Download and run the official Python installer for Windows.

```powershell
# Official installer (recommended)
# Download from https://www.python.org/downloads/windows/
```

--------------------------------

### Run MCP Server (HTTP)

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/README.md

Installs and runs the MCP server using PyPI with HTTP transport. Ensure `uvx` is installed and configured.

```bash
uvx --from mcpforunityserver mcp-for-unity --transport http --http-url http://localhost:8080
```

--------------------------------

### Project Info Resource

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/tools-reference.md

Read `mcpforunity://project/info` to detect project capabilities before making assumptions about UI, input, or rendering setup. This resource returns fields detailing the project's configuration and installed packages.

```APIDOC
## Project Info Resource

### Description
Read `mcpforunity://project/info` to detect project capabilities before making assumptions about UI, input, or rendering setup.

### Returned Fields

- **projectRoot** (string) - Absolute path to project root
- **projectName** (string) - Project folder name
- **unityVersion** (string) - e.g. "2022.3.20f1"
- **platform** (string) - Active build target e.g. "StandaloneWindows64"
- **assetsPath** (string) - Absolute path to Assets folder
- **renderPipeline** (string) - "BuiltIn", "Universal", "HighDefinition", or "Custom"
- **activeInputHandler** (string) - "Old", "New", or "Both"
- **packages.ugui** (bool) - `com.unity.ugui` installed (Canvas, Image, Button, etc.)
- **packages.textmeshpro** (bool) - `com.unity.textmeshpro` installed (TMP_Text, TMP_InputField)
- **packages.inputsystem** (bool) - `com.unity.inputsystem` installed (InputAction, PlayerInput)
- **packages.uiToolkit** (bool) - Always `true` for Unity 2021.3+ (UIDocument, VisualElement, UXML/USS)
- **packages.screenCapture** (bool) - `com.unity.modules.screencapture` enabled (ScreenCapture API for screenshots)

### Key Decision Points

- **UI system**: If `packages.uiToolkit` is true (always for Unity 2021+), use `manage_ui` for UI Toolkit workflows (UXML/USS). If `packages.ugui` is true, use Canvas + uGUI components via `batch_execute`. UI Toolkit is preferred for new UI — it uses a frontend-like workflow (UXML for structure, USS for styling).
- **Text**: If `packages.textmeshpro` is true, use `TextMeshProUGUI` instead of legacy `Text`.
- **Input**: Use `activeInputHandler` to decide EventSystem module — `StandaloneInputModule` (Old) vs `InputSystemUIInputModule` (New). See [workflows.md — Input System](workflows.md#input-system-old-vs-new).
- **Shaders**: Use `renderPipeline` to pick correct shader names — `Standard` (BuiltIn) vs `Universal Render Pipeline/Lit` (URP) vs `HDRP/Lit` (HDRP).
```

--------------------------------

### Start and Verify Unity Bridge

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/migrations/v6_NEW_UI_CHANGES.md

Use this snippet to start the Unity Bridge lifecycle and verify its health. Ensure the bridge is started before calling Verify.

```csharp
var bridge = MCPServiceLocator.Bridge;
bridge.Start();

var result = bridge.Verify(bridge.CurrentPort);
if (result.Success && result.PingSucceeded)
{
    Debug.Log("Bridge is healthy");
}
```

--------------------------------

### Install a Unity Package

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/tools-reference.md

Installs a specified Unity package. The package can be identified by name, name@version, a Git URL, or a file path. Polling the status is recommended to confirm completion.

```python
manage_packages(action="add_package", package="com.unity.inputsystem")
```

```python
# Poll until complete:
manage_packages(action="status", job_id="<job_id>")
```

--------------------------------

### Start Light Baking

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Initiates the light baking process. Use --sync to wait for completion.

```bash
unity-mcp graphics bake-start
```

```bash
unity-mcp graphics bake-start --sync
```

--------------------------------

### Install Unity MCP CLI via pip

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Install the Unity MCP CLI from source using pip. Ensure you are in the Server directory and have Python 3.10+ installed. Use 'pip install -e .' for standard installation or 'uv pip install -e .' with uv.

```bash
# Navigate to the Server directory
cd /path/to/unity-mcp/Server

# Install in development mode
pip install -e .

# Or install with uv (recommended)
uv pip install -e .
```

--------------------------------

### List Installed Unity Packages

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/CLI_EXAMPLE.md

Lists all installed packages in the Unity project.

```bash
unity-mcp packages list
```

--------------------------------

### Install Package from Git URL

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

Install a package directly from a Git URL. Exercise caution and ensure the source is trusted due to security implications.

```python
manage_packages(
    action="add_package",
    package="https://github.com/GlitchEnzo/NuGetForUnity.git?path=/src/NuGetForUnity"
)
```

```python
manage_packages(action="status", job_id="<job_id>")
```

--------------------------------

### Example Prompt: Build Player Controller

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/i18n/README-zh.md

An example prompt for generating a simple player controller script. This showcases MCP's ability to assist with scripting and core game mechanics.

```text
Build a simple player controller
```

--------------------------------

### Install Unity MCP Package

Source: https://context7.com/coplaydev/unity-mcp/llms.txt

Install the Unity MCP package using the Package Manager with the provided git URL or via OpenUPM. Optionally, install the Python CLI.

```bash
# Unity Package Manager URL (main branch)
https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main
```

```bash
# Or via OpenUPM
openupm add com.coplaydev.unity-mcp
```

```bash
# Python CLI installation (optional)
cd Server && pip install -e .
```

--------------------------------

### Add OpenUPM Registry and Install Package

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

Configure the package manager to use the OpenUPM registry and install a package from it. Ensure to resolve packages after adding the registry.

```python
manage_packages(
    action="add_registry",
    name="OpenUPM",
    url="https://package.openupm.com",
    scopes=["com.cysharp"]
)
```

```python
manage_packages(action="resolve_packages")
```

```python
manage_packages(action="add_package", package="com.cysharp.unitask")
```

```python
manage_packages(action="status", job_id="<job_id>")
```

--------------------------------

### Verify Unity MCP CLI Installation

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Verify the installation of the Unity MCP CLI by checking its version, help output, and connection status to the Unity editor.

```bash
# Check version
unity-mcp --version

# Check help
unity-mcp --help

# Test connection to Unity
unity-mcp status
```

--------------------------------

### Start Unity MCP Server

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Manually start the Unity MCP server using uv. Ensure the Unity Editor is running with the MCP plugin enabled and the server is configured for HTTP transport on port 8080.

```bash
# The server is typically started via the Unity-MCP window, select HTTP local, and start server, or try this manually:
cd /path/to/unity-mcp/Server
uv run mcp-for-unity --transport http --http-url http://localhost:8080
```

--------------------------------

### Manual Roslyn DLL Installation

Source: https://github.com/coplaydev/unity-mcp/blob/beta/README.md

Manually install Roslyn DLLs by downloading them from NuGet and placing them in the `Assets/Plugins/Roslyn/` folder. Ensure .NET compatibility and add `USE_ROSLYN` to Scripting Define Symbols.

```csharp
Assets/Plugins/Roslyn/
```

--------------------------------

### Install MCP for Unity via OpenUPM

Source: https://github.com/coplaydev/unity-mcp/blob/beta/README.md

Install the MCP for Unity package using the OpenUPM command-line interface. Ensure OpenUPM is configured in your Unity project.

```bash
openupm add com.coplaydev.unity-mcp
```

--------------------------------

### Start Profiling Session

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/tools-reference.md

Initiate a Unity Profiler session. Optionally record data to a file and enable allocation callstacks.

```python
# Start profiling (optionally record to file)
manage_profiler(action="profiler_start")
```

```python
manage_profiler(action="profiler_start", log_file="Assets/profiler.raw", enable_callstacks=True)
```

--------------------------------

### Configure Service Token for Auth Service

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/REMOTE_SERVER_AUTH.md

Example of setting up a service token for server-to-server authentication with the external auth service.

```bash
--api-key-service-token-header X-Service-Token \
--api-key-service-token "your-server-secret"
```

--------------------------------

### Create a Complete Scene from Scratch

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

This workflow demonstrates creating a new scene and then batch creating environment objects like ground, light, and player.

```python
# 1. Create new scene
manage_scene(action="create", name="GameLevel", path="Assets/Scenes/")

# 2. Batch create environment objects
batch_execute(commands=[
    {"tool": "manage_gameobject", "params": {
        "action": "create", "name": "Ground", "primitive_type": "Plane",
        "position": [0, 0, 0], "scale": [10, 1, 10]
    }},
    {"tool": "manage_gameobject", "params": {
        "action": "create", "name": "Light", "primitive_type": "Cube"
    }},
    {"tool": "manage_gameobject", "params": {
        "action": "create", "name": "Player", "primitive_type": "Capsule",
        "position": [0, 1, 0]
    }}
])
```

--------------------------------

### Get Official Unity Documentation

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

Use the `unity_docs` tool to retrieve official documentation for specific Unity classes and members. This includes descriptions, signatures, parameters, and code examples.

```python
unity_docs(action="get_doc", class_name="NavMeshAgent", member_name="SetDestination")
```

--------------------------------

### Get Mesh Info and Extrude Faces

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/probuilder-guide.md

Retrieve face information including normals and directions, then use this to select and extrude specific faces. Ensure ProBuilder is installed before use.

```python
# Step 1: Get face info with directions
result = manage_probuilder(action="get_mesh_info", target="MyCube",
    properties={"include": "faces"})

# Response includes per-face:
#   index: 0, normal: [0, 1, 0], center: [0, 0.5, 0], direction: "top"
#   index: 1, normal: [0, -1, 0], center: [0, -0.5, 0], direction: "bottom"
#   index: 2, normal: [0, 0, 1], center: [0, 0, 0.5], direction: "front"
#   ...

# Step 2: Use the direction labels to pick faces
# Want to extrude the top? Find the face with direction="top"
manage_probuilder(action="extrude_faces", target="MyCube",
    properties={"faceIndices": [0], "distance": 1.5})
```

--------------------------------

### Manage Line Renderers

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/CLI_USAGE.md

Create and configure line renderers. Specify start and end points for lines, or a radius for circles.

```bash
unity-mcp vfx line info "LaserBeam"
```

```bash
unity-mcp vfx line create-line "Line" --start 0 0 0 --end 10 5 0
```

```bash
unity-mcp vfx line create-circle "Circle" --radius 5
```

--------------------------------

### Start Lightmap Bake

Source: https://context7.com/coplaydev/unity-mcp/llms.txt

Initiates the lightmap baking process. Can be run asynchronously to avoid blocking the main thread.

```python
manage_graphics(action="bake_start", async_bake=True)
```

--------------------------------

### Manage Unity Instances

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/CLI_EXAMPLE.md

Commands for listing, setting, and viewing the current active Unity instance.

```bash
unity-mcp instance list
```

```bash
unity-mcp instance set "ProjectName@abc"
```

```bash
unity-mcp instance current
```

--------------------------------

### Install Python 3.12 on macOS

Source: https://github.com/coplaydev/unity-mcp/wiki/1.-Fix-Unity-MCP-and-Cursor,-VSCode,-Windsurf,-Rider

Use the official installer or Homebrew to install Python 3.12 on macOS.

```bash
# Option A: Official installer (recommended)
# Download from https://www.python.org/downloads/

# Option B: Homebrew
brew install python@3.12
```

--------------------------------

### List Unity Instances

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/CLI_USAGE.md

Display a list of available Unity instances that can be connected to.

```bash
unity-mcp instance list
```

--------------------------------

### Create Light and Reflection Probes

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Create new light probes with a specified name and spacing, or reflection probes with custom resolution and mode.

```bash
unity-mcp graphics bake-create-probes --name "LightProbes" --spacing 5
```

```bash
unity-mcp graphics bake-create-reflection --name "ReflProbe" --resolution 512 --mode Realtime
```

--------------------------------

### Install Claude Code CLI via npm with System Node

Source: https://github.com/coplaydev/unity-mcp/wiki/2.-Fix-Unity-MCP-and-Claude-Code

Installs the Claude Code CLI globally using npm. If Node.js is not installed, it can be installed via Homebrew on macOS. Use 'which claude' to verify its presence on the PATH.

```bash
# If you don't have Node yet (macOS):
brew install node

# Install Claude Code CLI globally
npm install -g @anthropic-ai/claude-code

# Verify it's on PATH (typical: /opt/homebrew/bin/claude or /usr/local/bin/claude)
which claude
claude --version
```

--------------------------------

### Install Claude Code CLI (macOS/Linux/WSL)

Source: https://github.com/coplaydev/unity-mcp/wiki/2.-Fix-Unity-MCP-and-Claude-Code

Installs the Claude Code CLI using a curl script. Run 'claude doctor' to verify the installation.

```bash
curl -fsSL https://claude.ai/install.sh | bash
claude doctor
```

--------------------------------

### Unity MCP CLI Command Structure Example

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Illustrates the general structure of Unity MCP CLI commands, showing the placement of global options, command groups, subcommands, arguments, and options.

```bash
unity-mcp [GLOBAL_OPTIONS] COMMAND_GROUP [SUBCOMMAND] [ARGUMENTS] [OPTIONS]
```

```bash
unity-mcp -f json gameobject create "MyCube" --primitive Cube --position 0 1 0
#         ^^^^^^^ ^^^^^^^^^^^ ^^^^^^ ^^^^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
```

--------------------------------

### Create a Fresh Scene for Generation

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

Use `manage_scene(action="create")` to start with a clean, empty scene. This prevents conflicts with default scene objects.

```python
# Step 0: Create fresh empty scene (replaces current scene entirely)
manage_scene(action="create", name="MyGeneratedScene", path="Assets/Scenes/")

# Now proceed with the phased execution plan...
# Phase 1: Environment (camera, lights) — no conflicts
# Phase 2: Objects (GameObjects)
# Phase 3: Materials
# etc.
```

--------------------------------

### Install Claude Code CLI (Windows PowerShell)

Source: https://github.com/coplaydev/unity-mcp/wiki/2.-Fix-Unity-MCP-and-Claude-Code

Installs the Claude Code CLI using a PowerShell command. Run 'claude doctor' to verify the installation.

```powershell
irm https://claude.ai/install.ps1 | iex
claude doctor
```

--------------------------------

### Input Handling with Old Input Manager

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

Example script demonstrating input handling using `Input.GetAxis()` and `Input.GetKeyDown()` with the old Input Manager.

```csharp
// Input.GetAxis / Input.GetKey — works with old Input Manager
void Update()
{
    float h = Input.GetAxis("Horizontal");
    float v = Input.GetAxis("Vertical");
    transform.Translate(new Vector3(h, 0, v) * speed * Time.deltaTime);

    if (Input.GetKeyDown(KeyCode.Space))
        Jump();

    if (Input.GetMouseButtonDown(0))
        Fire();
}
```

--------------------------------

### Fetch Unity Manual and Package Documentation

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

Retrieve specific Unity Manual pages using their slug or fetch documentation for a particular package by specifying the package name, page, and version.

```python
# Fetch Unity Manual pages (execution order, scripting concepts, etc.)
unity_docs(action="get_manual", slug="execution-order")
```

```python
# Fetch package-specific documentation
unity_docs(action="get_package_doc",
           package="com.unity.render-pipelines.universal",
           page="2d-index", pkg_version="17.0")
```

--------------------------------

### Configuration Flow from CLI/Env Vars

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/reference/REMOTE_SERVER_AUTH_ARCHITECTURE.md

Illustrates the flow of configuration settings from command-line arguments or environment variables through parsing, validation, and service initialization.

```text
CLI args / env vars
       |
       v
main.py: parser.parse_args()
       |
       +-- config.http_remote_hosted = args or env
       +-- config.api_key_validation_url = args or env
       +-- config.api_key_login_url = args or env
       +-- config.api_key_cache_ttl = args or env (float)
       +-- config.api_key_service_token_header = args or env
       +-- config.api_key_service_token = args or env
       |
       +-- Validate: remote-hosted requires validation URL
       |     (exits with code 1 if missing)
       |
       v
create_mcp_server()
       |
       +-- get_unity_instance_middleware()  ->  registers middleware
       |
       +-- if remote-hosted + validation URL:
       |     ApiKeyService(
       |       validation_url, cache_ttl,
       |       service_token_header, service_token
       |     )
       |
       +-- WebSocketRoute("/hub/plugin", PluginHub)
       |
       +-- if not remote-hosted:
             register CLI routes (/api/command, /api/instances, /api/custom-tools)
```

--------------------------------

### Camera Management - Basic

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Commands for checking Cinemachine availability, listing cameras, and creating basic cameras.

```bash
unity-mcp camera ping
```

```bash
unity-mcp camera list
```

```bash
unity-mcp camera create
```

--------------------------------

### Install Claude CLI with NVM Node on macOS

Source: https://github.com/coplaydev/unity-mcp/wiki/3.-Common-Setup-Problems

Install and use the LTS version of Node.js via NVM to avoid conflicts with Homebrew's ICU versions when installing the Claude CLI.

```bash
nvm install --lts
nvm use --lts
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Validate Scene Physics Setup

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/tools-reference.md

Validates the physics setup for the entire scene or a specific target object.

```python
manage_physics(action="validate")
```

```python
manage_physics(action="validate", target="Player")
```

--------------------------------

### Install Claude Code CLI via npm with NVM

Source: https://github.com/coplaydev/unity-mcp/wiki/2.-Fix-Unity-MCP-and-Claude-Code

Installs a specific Node.js version using NVM, then installs the Claude Code CLI globally within that Node environment. Use 'which claude' to confirm its location.

```bash
# Install/select a Node version
nvm install v21.7.1
nvm use v21.7.1

# Install Claude Code CLI into this Node's global prefix
npm install -g @anthropic-ai/claude-code

# Verify it's under NVM
which claude
claude --version
```

--------------------------------

### Create a New Camera

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/CLI_EXAMPLE.md

Create a new camera with a specified name and preset, linking it to follow and look-at targets.

```bash
unity-mcp camera create --name "Cam" --preset follow --follow "Player"
```

--------------------------------

### List Installed Packages

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/tools-reference.md

Lists all currently installed Unity packages. This is an asynchronous operation that returns a job ID, which can then be used to poll for status.

```python
manage_packages(action="list_packages")
```

```python
# Returns job_id, then poll:
manage_packages(action="status", job_id="<job_id>")
```

--------------------------------

### Bake Light Probes and Reflection Probes

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

Use `manage_graphics` to bake light probes for dynamic objects and reflection probes for interior rooms. Ensure baking is performed in Edit mode.

```python
manage_graphics(action="bake_create_light_probe_group", name="MainProbeGrid",
    position=[0, 1.5, 0], grid_size=[5, 3, 5], spacing=3.0)
```

```python
manage_graphics(action="bake_create_reflection_probe", name="RoomReflection",
    position=[0, 2, 0], size=[8, 4, 8], resolution=256,
    hdr=True, box_projection=True)
```

--------------------------------

### Configure Light Baking Settings

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

Set up lightmaps, light probes, and reflection probes for baked GI. Ensure static objects are marked to contribute to GI and configure lightmap settings appropriately for desired quality and performance.

```python
# 1. Set lights to Baked or Mixed mode
manage_components(action="set_property", target="Directional Light",
    component_type="Light", properties={"lightmapBakeType": 1})  # 1 = Mixed

# 2. Mark static objects for lightmapping
manage_gameobject(action="modify", target="Environment",
    component_properties={"StaticFlags": "ContributeGI"})

# 3. Configure lightmap settings
manage_graphics(action="bake_get_settings")
manage_graphics(action="bake_set_settings", settings={
    "lightmapper": 1,           # 1 = Progressive GPU
    "directSamples": 32,
    "indirectSamples": 128,
    "maxBounces": 4,
    "lightmapResolution": 40
})
```

--------------------------------

### Manage Unity Prefabs

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/CLI_EXAMPLE.md

Open, save, close, create, or modify prefabs in the Unity project.

```bash
unity-mcp prefab open "Assets/Prefabs/File.prefab"
```

```bash
unity-mcp prefab save
```

```bash
unity-mcp prefab close
```

```bash
unity-mcp prefab create "GameObject" --path "Assets/Prefabs"
```

```bash
unity-mcp prefab modify "Assets/Prefabs/File.prefab" --delete-child Child1
```

```bash
unity-mcp prefab modify "Assets/Prefabs/File.prefab" --target Weapon --position "0,1,2"
```

```bash
unity-mcp prefab modify "Assets/Prefabs/File.prefab" --set-property "Rigidbody.mass=5"
```

--------------------------------

### Checking Available Options with --help

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Always use the --help flag to verify available options for any command before assuming they exist. This prevents errors from using non-existent options.

```bash
# Check available options for any command
unity-mcp gameobject modify --help
unity-mcp material assign --help
unity-mcp prefab create --help
```

--------------------------------

### Input Handling with New Input System (PlayerInput)

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

Example script for handling input using the new Input System with a PlayerInput component. Uses callbacks for actions like 'Move' and 'Jump'.

```csharp
using UnityEngine;
using UnityEngine.InputSystem;

public class PlayerController : MonoBehaviour
{
    public float speed = 5f;
    private Vector2 moveInput;

    // Called by PlayerInput component via SendMessages or UnityEvents
    public void OnMove(InputValue value)
    {
        moveInput = value.Get<Vector2>();
    }

    public void OnJump(InputValue value)
    {
        if (value.isPressed)
            Jump();
    }

    void Update()
    {
        Vector3 move = new Vector3(moveInput.x, 0, moveInput.y);
        transform.Translate(move * speed * Time.deltaTime);
    }
}
```

--------------------------------

### Install Roslyn DLLs via MCP for Unity Menu

Source: https://github.com/coplaydev/unity-mcp/blob/beta/README.md

Install required Roslyn DLLs for runtime code execution by navigating the MCP for Unity menu. This is the recommended one-click approach.

```csharp
Window > MCP For Unity > Install Roslyn DLLs
```

--------------------------------

### Create and Configure Unity Cameras

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

Create and configure standard Unity cameras using the manage_camera function. This includes setting field of view, near/far clipping planes, and pointing the camera at a specific target.

```python
# Tier 1 actions work with plain Unity Camera
manage_camera(action="create_camera", properties={
    "name": "MainCam", "fieldOfView": 50
})
```

```python
# Set lens
manage_camera(action="set_lens", target="MainCam", properties={
    "fieldOfView": 60, "nearClipPlane": 0.1, "farClipPlane": 1000
})
```

```python
# Point camera at target (uses manage_gameobject look_at under the hood)
manage_camera(action="set_target", target="MainCam", properties={
    "lookAt": "Player"
})
```

--------------------------------

### Editor Readiness Snapshot

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/resources-reference.md

Use this resource to check editor readiness before performing tool operations. Ensure 'ready_for_tools' is true and 'is_compiling' is false before proceeding.

```json
{
  "unity_version": "2022.3.10f1",
  "is_compiling": false,
  "is_domain_reload_pending": false,
  "play_mode": {
    "is_playing": false,
    "is_paused": false
  },
  "active_scene": {
    "path": "Assets/Scenes/Main.unity",
    "name": "Main"
  },
  "ready_for_tools": true,
  "blocking_reasons": [],
  "recommended_retry_after_ms": null,
  "staleness": {
    "age_ms": 150,
    "is_stale": false
  }
}
```

--------------------------------

### Install or Remove Packages

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Adds a package to the project or removes an existing one. Version can be specified. Use --force to skip confirmation.

```bash
unity-mcp packages add "com.unity.cinemachine"
```

```bash
unity-mcp packages add "com.unity.cinemachine@4.1.1"
```

```bash
unity-mcp packages remove "com.unity.cinemachine"
```

```bash
unity-mcp packages remove "com.unity.cinemachine" --force
```

--------------------------------

### Get Mesh Face Information

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/tools-reference.md

Retrieves detailed information about the faces of a specified ProBuilder mesh. The 'include' parameter can specify the level of detail, such as 'faces' to get normals and direction labels.

```python
manage_probuilder(action="get_mesh_info", target="MyCube", properties={"include": "faces"})
```

--------------------------------

### Get Help with Unity MCP CLI Commands

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Access help information for the Unity MCP CLI. You can get general help, help for a command group, or specific help for a command.

```bash
# List all commands
unity-mcp --help

# Help for a command group
unity-mcp gameobject --help

# Help for a specific command
unity-mcp gameobject create --help
```

--------------------------------

### Manage Scene Components and GameObjects

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

Use these commands to add, remove, and modify components on GameObjects, set properties, and configure the camera. Useful for scene setup and verification.

```python
manage_components(action="remove", target="Light", component_type="MeshRenderer")
manage_components(action="remove", target="Light", component_type="MeshFilter")
manage_components(action="remove", target="Light", component_type="BoxCollider")
manage_components(action="add", target="Light", component_type="Light")
manage_components(action="set_property", target="Light", component_type="Light",
    property="type", value="Directional")
```

```python
manage_gameobject(action="modify", target="Main Camera", position=[0, 5, -10],
    rotation=[30, 0, 0])
```

```python
manage_camera(action="screenshot")
```

```python
manage_scene(action="save")
```

--------------------------------

### Camera Management - Create with Presets

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Commands to create cameras using various Cinemachine presets like follow, third-person, dolly, top-down, side-scroller, and static.

```bash
unity-mcp camera create --name "FollowCam" --preset follow --follow "Player" --look-at "Player"
```

```bash
unity-mcp camera create --preset third_person --follow "Player" --fov 50
```

```bash
unity-mcp camera create --preset dolly --look-at "Player"
```

```bash
unity-mcp camera create --preset top_down --follow "Player"
```

```bash
unity-mcp camera create --preset side_scroller --follow "Player"
```

```bash
unity-mcp camera create --preset static --fov 40
```

--------------------------------

### List Cameras in Unity

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/CLI_EXAMPLE.md

List all available cameras in the Unity scene.

```bash
unity-mcp camera list
```

--------------------------------

### Start Long-Running Operation with Pending Response in C#

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/reference/CUSTOM_TOOLS.md

Initiates a long-running operation by returning a `PendingResponse`. This signals that the job has started and specifies the interval in seconds for the server to poll for status updates. This is the first step in setting up a polled tool.

```csharp
return new PendingResponse("message", pollIntervalSeconds);
```

--------------------------------

### Get Info for Assets

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Use 'info' commands to retrieve detailed information about assets like materials or prefabs. This is helpful when you need to know specific properties or configurations.

```bash
unity-mcp material info "Assets/Materials/Mat.mat"
```

```bash
unity-mcp asset info "Assets/Prefabs/Player.prefab"
```

--------------------------------

### Get Pipeline Information

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/tools-reference.md

Retrieves information about the current rendering pipeline.

```python
manage_graphics(action="pipeline_get_info")
```

--------------------------------

### Get Package Information

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Retrieves detailed information about a specific package.

```bash
unity-mcp packages info "com.unity.cinemachine"
```

--------------------------------

### Get Material Information

Source: https://github.com/coplaydev/unity-mcp/blob/beta/Server/src/cli/CLI_USAGE_GUIDE.md

Retrieves information about a specified material asset.

```bash
unity-mcp material info "Assets/Materials/Mat.mat"
```

--------------------------------

### Cinemachine Setup: Multi-Camera with Blending

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/workflows.md

Workflow for setting up multiple cameras with different priorities for blending, such as a primary gameplay camera and a secondary cinematic camera.

```python
# 1. Read current cameras
# Read mcpforunity://scene/cameras

# 2. Create gameplay camera (highest priority = active by default)
manage_camera(action="create_camera", properties={
    "name": "GameplayCam", "preset": "follow",
    "follow": "Player", "lookAt": "Player", "priority": 10
})

# 3. Create cinematic camera (lower priority, activated on demand)
manage_camera(action="create_camera", properties={
    "name": "CinematicCam", "preset": "dolly",
    "lookAt": "CutsceneTarget", "priority": 5
})
```

--------------------------------

### Get Asset Information

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/CLI_EXAMPLE.md

Retrieve detailed information about a specific asset.

```bash
unity-mcp asset info "Assets/Materials/File.mat"
```

--------------------------------

### Fetch Unity Package Documentation

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/tools-reference.md

Use `unity_docs` with the `get_package_doc` action to fetch documentation for a specific package page. Requires package name, page slug, and package version.

```python
unity_docs(action="get_package_doc", package="com.unity.render-pipelines.universal",
           page="2d-index", pkg_version="17.0")
```

--------------------------------

### Get Scene Hierarchy

Source: https://github.com/coplaydev/unity-mcp/blob/beta/docs/guides/CLI_USAGE.md

Retrieve the hierarchy of the current Unity scene.

```bash
unity-mcp scene hierarchy
```

--------------------------------

### Get Memory Usage Statistics

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/tools-reference.md

Retrieves detailed memory usage statistics.

```python
manage_graphics(action="stats_get_memory")
```

--------------------------------

### Get Build Settings

Source: https://github.com/coplaydev/unity-mcp/blob/beta/unity-mcp-skill/references/tools-reference.md

Retrieves the current build settings for the Unity project.

```python
manage_scene(action="get_build_settings")
```