Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
# Windows
Test-Path "$env:USERPROFILE\.local\bin\uvx.exe"
# macOS/Linux
which uvx
If not installed:
In the Unity editor, open Window → MCP → Local Setup
Click "Install" or "Setup Environment"
Wait for automatic download and installation of uvx and related dependencies
Restart the terminal/IDE to load the new environment variables
Plugin source:
Unity MCP Server: mcpforunityserver>=0.0.0a0
Deployment
1. Start the MCP Server
Check uvx Installation Location
uvx is usually installed in the following locations:
Windows:
# Standard installation path
$env:USERPROFILE\.local\bin\uvx.exe
# Or
C:\Users\<Username>\.local\bin\uvx.exe
# Check if it exists
Test-Path "$env:USERPROFILE\.local\bin\uvx.exe"
macOS/Linux:
~/.local/bin/uvx
# Or
/usr/local/bin/uvx
If uvx Does Not Exist
⚠️ Prompt the user:
uvx tool not found. Please do the following in the Unity editor:
1. Open Window → MCP → Local Setup
2. Click "Install Dependencies" or "Setup Local Environment"
3. Wait for the installation to complete
4. Try starting the MCP Server again
Start Command
Windows (dynamic path):
$uvxPath = "$env:USERPROFILE\.local\bin\uvx.exe"
if (Test-Path $uvxPath) {
& $uvxPath --prerelease explicit --from "mcpforunityserver>=0.0.0a0" mcp-for-unity --transport http --http-url http://localhost:8080 --project-scoped-tools
} else {
Write-Host "Error: uvx not found. Please install dependencies by clicking MCP → Local Setup in Unity."
}
// Add component{"name":"manage_components","arguments":{"action":"add","target":"Tree2D","component_type":"SpriteRenderer"}}// Set property ⚠️ Pay attention to type format{"action":"set_property","target":"Tree2D","component_type":"SpriteRenderer","property":"color","value":{"r":0.1,"g":0.5,"b":0.2,"a":1.0}// ✅ Object format// ❌ Incorrect: [0.1, 0.5, 0.2, 1]}
Scene Management
// Create scene{"name":"manage_scene","arguments":{"action":"create","name":"MyScene","path":"MyFolder"}}// Save scene{"action":"save"}// Get hierarchy{"action":"get_hierarchy","page_size":50}
The term 'uvx' is not recognized as a cmdlet, function, operable program, or script file.
# Or
Cannot find part of the path "C:\Users\xxx\.local\bin\uvx.exe"
Cause:
uvx is a dependency tool for Unity MCP and has not been installed yet
The installation path varies depending on the system/user
Resolution steps:
Install in Unity:
Menu: Window → MCP → Local Setup
Click: Install Dependencies or Setup Local Environment
Wait for the installation to complete (may take a few minutes)
Verify installation:
# Windows
Get-Command uvx
# Or
Test-Path "$env:USERPROFILE\.local\bin\uvx.exe"
# macOS/Linux
which uvx
Restart the terminal to load the new PATH environment variable
Dynamic path detection script:
function Get-UvxPath {
# Try common paths
$paths = @(
"$env:USERPROFILE\.local\bin\uvx.exe",
"$env:LOCALAPPDATA\uv\uvx.exe",
"C:\Program Files\uv\uvx.exe"
)
foreach ($path in $paths) {
if (Test-Path $path) { return $path }
}
# Try to find from PATH
$uvx = Get-Command uvx -ErrorAction SilentlyContinue
if ($uvx) { return $uvx.Source }
return $null
}
$uvxPath = Get-UvxPath
if (-not $uvxPath) {
Write-Host "❌ uvx not found. Please install it by clicking Window → MCP → Local Setup in Unity."
exit 1
}
Write-Host "✅ Found uvx: $uvxPath"
Issue 1: Unable to Set SpriteRenderer.sprite
Symptoms:
Failed to convert value for property 'sprite' to type 'Sprite'
Cause:
manage_texture creates a Texture2D, but SpriteRenderer requires a Sprite type
The API does not support directly converting a path string to a Sprite reference
Solutions:
Manual method (recommended): Drag the texture onto the SpriteRenderer's Sprite field in Unity, and Unity will automatically convert it
Editor script: Write a tool script under the Editor folder to batch assign values
Pre-create Sprite: Use Unity's Sprite Editor to convert the texture into a Sprite asset
Issue 2: Color Format Error
Symptoms:
Error converting token to UnityEngine.Color: Error reading JObject from JsonReader
Solution: Use the object format {"r":x,"g":y,"b":z,"a":w} instead of the array [x,y,z,w]
Issue 3: Session Expired
Symptoms:
Missing session ID
Bad Request: Missing session ID
Solution:
Re-initialize to get a new Session ID
Ensure every request includes the mcp-session-id Header
Issue 4: Unity Instance Not Found / Cannot Find Active Instance
Symptoms:
{"instance_count":0,"instances":[]}
Or
Active instance set to ... : false
Cause:
The MCP Server has started, but the Unity editor has not yet established a connection with the Server
The MCP Session in Unity has not been started
Resolution steps:
Ensure the Unity editor is open (and the project is loaded)
Start the MCP Session in Unity:
Menu: Window → MCP or MCP → Session
In the MCP window, find the Session or Connection section
Click the "Start Session" or "Connect" button
Wait for the status to change to "Connected" or "Running"
Check connection status:
The MCP window should display: Status: Connected or Transport: HTTP
Or display the currently connected Server address: http://localhost:8080
❌ "filter": "All" → ✅ Not supported, omit or use the correct parameter
Workflow Patterns
Pattern 1: Complete Workflow for Creating a 2D Object
1. Create GameObject (empty object)
manage_gameobject: create
2. Add SpriteRenderer component
manage_components: add, component_type=SpriteRenderer
3. Set color
manage_components: set_property, property=color, value={r,g,b,a}
4. Manually assign Sprite (API limitation)
Or drag and drop the texture onto the Sprite field in Unity
1. Execute operation
2. Check console logs
read_console: get
3. Verify result
manage_scene: get_hierarchy
4. If there is an error, read specific component information
resources/read: mcpforunity://scene/gameobject/{id}/components
API Limitations
Limitation
Description
Workaround
Sprite assignment
Cannot set Sprite directly via API
Manual drag-and-drop or editor script
Texture import settings
Cannot modify Texture Import Settings
Pre-configure or set manually in Unity
Complex components
Some component properties are not supported
Configure manually using the Unity editor
Script creation
Content needs escaping
Use simple scripts or templates
Best Practices
Always save the scene Execute manage_scene: save after batch operations
Check the console Regularly use read_console to view errors
Use Instance ID Use the Instance ID instead of the name when operating on specific objects
Batch operations Use loops for batch creation to reduce the number of API calls
Error handling Check the success field after each operation
