URP Import Helper / Docs / CLI & MCP Quick Start

CLI & MCP Quick Start — URP Import Helper

By Thomp Tech · Optional Unity 6+ integration

URP Import Helper works normally inside Unity without the CLI or MCP. Use this guide only if you want to analyze or convert materials through commands or an AI agent.

1. Requirements

A Unity 6+ project with URP installed and active.
URP Import Helper installed in that project. Owning the Asset Store asset alone does not register commands.
Unity CLI installed and connected to the relevant Unity Editor/project, or an MCP-capable client connected through unity mcp.
Unity's optional com.unity.pipeline version 0.8.0-exp.1 installed in the project through Package Manager. This exact version is the currently tested adapter pin; other versions do not enable these commands unless a later URP Import Helper release explicitly supports them.

The tool includes its optional Editor/Pipeline adapter. When the required Pipeline version is present, Unity compiles the adapter and registers the commands. The core tool still works without Pipeline, including in the best-effort Unity 2022.3 Editor workflow; the CLI/MCP adapter is Unity 6+ only.

2. Discover the commands

With the Unity CLI configured for your project, list URP Import Helper commands:

unity command --query urpih

You should find:

urpih_analyze_materials — read-only check of a .mat file or an Assets/... folder.
urpih_convert_materials — converts only materials judged safe, and requires confirm true.

If they aren't listed, see Troubleshooting below. An unsupported Pipeline version intentionally leaves the adapter inactive; it doesn't prevent the normal Editor menu from working.

3. Analyze before you convert

Use a project-relative path such as Assets/MyImportedPack or a single Assets/.../Material.mat. Analyze first:

unity command urpih_analyze_materials --path Assets/MyImportedPack --result-only

This is read-only. It doesn't change materials, mode, pending imports, Undo state, or UI. Review the returned counts, materials, byShader, nextActions, outcome and severity before deciding what to do.

4. Confirm conversion

Only if you want to change the supported materials at that path:

unity command urpih_convert_materials --path Assets/MyImportedPack --confirm true --result-only

The operation rechecks eligibility and saves successful changes. Materials it cannot safely convert are left unchanged and reported. confirm false (or a missing required confirmation) does not convert anything. The commands do not follow your Ask/Auto/Report Only preference: the command itself is the explicit action.

If you're connected to an open Unity Editor, its named conversion step is available in Edit > Undo, and URP Import Helper saves reverted materials. A full Editor restart loses that Undo history.

5. Headless runs and MCP

A headless Unity CLI run opens the project without the interactive Editor. The project path goes before --:

unity run --command urpih_analyze_materials . -- --path Assets/MyImportedPack
unity run --command urpih_convert_materials . -- --path Assets/MyImportedPack --confirm true

Headless conversions have no Unity Undo. Commit or back up your project before conversion, and use version control to revert if necessary.

For MCP, start or configure Unity's MCP server for the target project (for example, unity mcp --project-path <project>), then connect it through your MCP-capable client. Give the agent a request like:

I installed Thomp Tech URP Import Helper. Check the materials in my imported asset folder, tell me what is safe to convert, and ask for confirmation before converting anything.

The two URPIH commands are exposed as MCP tools where supported. An agent should Analyze first, ask before converting, and report leftovers. A separate end-to-end agent-client usability test has not yet been completed; the command registration and raw MCP interface have been verified.

6. Understand the result

Commands return structured schema-v1 results. A CLI exit code 0 means a result was returned; it does not mean every material converted. Inspect:

outcome — readyToConvert, converted, finishedWithFailures, unityHandoff, nothingToConvert, or noMaterials as applicable.
severity — info, warning, or error.
counts — total, ready, converted, failed, not restored, and leftover counts.
nextActions — what to do next; give undoBeforeSaving priority when present.
project.batchMode — whether the command ran headlessly.

The result contains details only for materials needing explanation; a clean conversion may be counted without its own per-material row. Unity-supported and other shaders are grouped in byShader.

7. Troubleshooting and recovery

Commands aren't listed? Confirm the Helper is installed in this project, Unity has finished compiling, com.unity.pipeline is exactly 0.8.0-exp.1, and Editor/Pipeline was included in the installation. Check the Console for an adapter-load or unsupported-version message. Core Editor conversion still works without it.

URP inactive or files not found? The operation refuses without converting. Activate URP, or correct the Assets/... path, then Analyze again.

A command times out? Don't blindly retry Convert: an open Editor may finish and save the conversion after the CLI stops waiting. Run Analyze again first to see what remains. For large folders or a whole project, Unity CLI supports a longer timeout (for example --timeout 300).

Some materials remain unchanged? Review nextActions and material reasons. V1 converts only safely supported Built-in Standard (metallic workflow) materials to URP/Lit; it doesn't modify custom shaders or embedded model materials.

Result says notRestored? In a live Editor follow the Undo-before-saving instruction. In headless execution, inspect and revert with version control; a failed material can be saved partially converted when the headless Editor exits.

For ordinary import-time Ask/Auto/Report Only behavior, use Getting Started.

← Back: Getting Started