MCP for Blender
Menu Troubleshooting

Reference

Troubleshooting MCP for Blender Connection and Runtime Issues

Fix common MCP for Blender issues including ENOENT errors, connection timeouts, Poly Haven erratic behavior, Poly Pizza Cloudflare blocks, and addon version mismatches.

Most MCP for Blender issues fall into a few categories: the client cannot find uvx, the socket connection fails, or an integration is not enabled. This page walks through each.

spawn uvx ENOENT

GUI clients like Claude Desktop do not inherit your terminal's PATH. The fix is to use the full absolute path to uvx.

  1. In a terminal, run which uvx to get the full path (for example, /Users/you/.local/bin/uvx)
  2. Use that full path as the command in your MCP client config
  3. Fully quit and relaunch the client so the new config is loaded
Connection refused / Cannot connect to Blender

The MCP server cannot reach Blender's socket. Make sure both the addon and the server are running.

  1. Confirm the MCP for Blender addon is enabled in Edit → Preferences → Add-ons
  2. In the 3D viewport, press N to open the sidebar, then select the MCP for Blender tab
  3. If the panel says Not connected, click Connect to MCP server (the addon normally connects automatically when Blender loads)
  4. Verify port 9876 is not blocked by a firewall or another process
Timeout errors

Complex operations can exceed the 180-second socket timeout. Simplify the request or break it into smaller steps. For example, instead of asking for a full scene with lighting, textures, and animation in one prompt, split it into separate prompts for layout, materials, and lighting.

Blender freezes during a Poly Haven download

Assets are downloaded on Blender's main thread, so the UI stops responding until the transfer finishes. File size grows roughly fourfold per resolution step, so ask for 1k or 2k unless the asset is held close to camera.

Poly Pizza download fails with Cloudflare challenge

The static asset host static.poly.pizza blocks datacenter, VPN, and cloud IPs with a Cloudflare challenge. Your API key is fine; the CDN never sees it. If you see a download failure:

  • Retry from a normal residential connection, or
  • Download the .glb manually from Poly Pizza and import it with File → Import → glTF 2.0
First command doesn't go through

Sometimes the first command after connecting fails silently. Retry the same prompt. It usually works on the second attempt.

Addon version mismatch

If the addon and the MCP server are out of sync, features may fail or behave unexpectedly.

  1. Run uvx mcp-for-blender install-addon to install the latest addon
  2. In Blender, disable and re-enable the MCP for Blender addon, or restart Blender
Multiple MCP server instances

Only run one instance of the MCP for Blender server at a time. Running both Cursor and Claude Desktop simultaneously causes conflicts because both clients try to connect to the same Blender socket on port 9876.

Blender running headless (-b mode)

Commands never execute when Blender is running in headless mode (blender -b). The addon requires a GUI to function. Run Blender normally, or use xvfb-run -a blender on a headless Linux server to provide a virtual display.

Have you tried turning it off and on again?

Restart both Claude Desktop (or your MCP client) and the MCP for Blender server. This resolves a surprising number of transient connection and state issues.