Complete setup guide — uv installation, PATH configuration, JSON config, Python version pinning, and dependency troubleshooting on Windows.
Claude Desktop communicates with Blender through the Model Context Protocol (MCP). The bridge is a local Python server (blender-mcp) managed by uvx. Claude spawns this server as a child process and exchanges JSON-RPC messages over stdio.
| Component | Role | Requirement |
|---|---|---|
uv / uvx | Python tool runner — installs & runs blender-mcp in an isolated env | Must be on PATH visible to Claude Desktop |
blender-mcp | MCP server — translates Claude tool calls to Blender Python API | Installed automatically by uvx |
| Blender addon | Socket server inside Blender listening on port 9000 | Must be enabled in Blender preferences |
claude_desktop_config.json | Tells Claude Desktop how to spawn the MCP server | Absolute paths required on Windows |
Run this in an Administrator PowerShell. The installer downloads uv.exe, uvx.exe, and uvw.exe to your user directory.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
After install, the binaries land at:
C:\Users\<YourName>\.local\bin\uv.exe
C:\Users\<YourName>\.local\bin\uvx.exe
C:\Users\<YourName>\.local\bin\uvw.exe
The installer modifies your PowerShell profile to add the bin folder to PATH — but this only takes effect in new shell sessions. Claude Desktop must be restarted after this step, as it caches the environment at launch.
The installer writes a profile script. If PowerShell's execution policy is Restricted (Windows default), it will block this script at every launch with a PSSecurityException. Fix it once:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
RemoteSigned allows locally created scripts (like the uv profile entry) to run freely, while still requiring internet-downloaded scripts to be signed. This is the recommended safe setting for developers.
Critical: blender-mcp v1.5.6 depends on supabase → storage3 → pyiceberg. The pyiceberg package has no pre-built wheel for Python 3.14 on Windows, causing a C-extension compile failure that requires MSVC. Pin to Python 3.12 instead.
| Python Version | pyiceberg wheel available | blender-mcp installs |
|---|---|---|
| 3.14 (system installed) | ✗ No — build from source | ✗ Fails (needs MSVC) |
| 3.12 (via uv) | ✓ Pre-built wheel | ✓ Works |
| 3.11 | ✓ Pre-built wheel | ✓ Works |
uv python install 3.12
uv cache clean
claude_desktop_config.jsonClaude Desktop reads its MCP server definitions from a JSON config file. Open it with:
notepad "$env:APPDATA\Claude\claude_desktop_config.json"
{
"mcpServers": {
"blender": {
"command": "C:\\Users\\ANJAN GANAPATHY K\\.local\\bin\\uvx.exe",
"args": ["--python", "3.12", "blender-mcp"]
}
}
}
| Key | Value | Why |
|---|---|---|
"command" | Full absolute path to uvx.exe | Claude Desktop inherits a limited PATH that may not include ~\.local\bin |
"args"[0] | "--python" | Tells uvx to use a specific Python version |
"args"[1] | "3.12" | Pins to Python 3.12 to avoid pyiceberg build failure on 3.14 |
"args"[2] | "blender-mcp" | The PyPI package name of the MCP server to run |
Backslashes in JSON must be doubled (\\). A single \ is an escape character in JSON and will silently corrupt the path. Use where.exe uvx in PowerShell to get the exact path, then double every backslash when pasting into JSON.
The blender-mcp server communicates with Blender via a local socket on port 9000. Blender must be running with the addon active — otherwise the server logs: Could not connect to Blender on startup. Will retry on first tool call.
9000)When connected successfully, the log shows: Server started and connected successfully followed by a ListToolsRequest listing all available Blender tools (scene info, object creation, render, history undo/redo, etc.)
| Error in Log | Root Cause | Fix |
|---|---|---|
spawn uvx ENOENT |
Claude Desktop can't find uvx — PATH not inherited |
Use absolute path to uvx.exe in config |
'uvx' is not recognized |
Same as above — cmd.exe fallback also fails | Absolute path in command field |
No module named blender_mcp |
Config using python -m blender_mcp instead of uvx blender-mcp |
Switch back to uvx-based config |
Microsoft Visual C++ 14.0 required |
Python 3.14 — pyiceberg has no wheel, tries to compile | Add --python 3.12 to args |
Could not connect to Blender |
Blender not running or addon not enabled | Open Blender, enable MCP addon |
PSSecurityException on profile |
PowerShell execution policy blocks uv profile script | Set-ExecutionPolicy RemoteSigned -Scope CurrentUser |
| Log file not found | Server never launched — ENOENT happened before any file was written | Fix PATH/command first, then check %APPDATA%\Claude\logs\ |
Get-Content "$env:APPDATA\Claude\logs\mcp-server-blender.log" -Tail 30
uv --version in a new PowerShell — should output uv 0.11.7 or laterwhere.exe uvx — should return path inside \.local\bin\claude_desktop_config.json uses absolute path to uvx.exe with --python 3.129000blender with a connected statusListToolsRequest and a tool list response — no ENOENT, no build errors# 1. Install uv powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # 2. Fix execution policy (new Admin PowerShell) Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser # 3. Install Python 3.12 uv python install 3.12 # 4. Clear uv cache uv cache clean # 5. Confirm uvx path where.exe uvx # 6. Open Claude Desktop config notepad "$env:APPDATA\Claude\claude_desktop_config.json" # 7. View logs after restart Get-Content "$env:APPDATA\Claude\logs\mcp-server-blender.log" -Tail 30
{
"mcpServers": {
"blender": {
"command": "C:\\Users\\ANJAN GANAPATHY K\\.local\\bin\\uvx.exe",
"args": ["--python", "3.12", "blender-mcp"]
}
}
}