Skip to main content
Most Blender MCP 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.
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
The MCP server cannot reach Blender’s socket. Make sure both the addon and the server are running.
  1. Confirm the Blender MCP addon is enabled in Edit → Preferences → Add-ons
  2. In the 3D viewport, press N to open the sidebar, then select the BlenderMCP tab
  3. Click Start MCP Server
  4. Verify port 9876 is not blocked by a firewall or another process
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.
Claude can sometimes behave inconsistently with Poly Haven. If Poly Haven tools return unexpected results or fail, retry the request. In most cases the second attempt succeeds.
The static asset host static.poly.pizza blocks datacenter, VPN, and cloud IPs with a Cloudflare challenge. 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
Sometimes the first command after connecting fails silently. Retry the same prompt. It usually works on the second attempt.
If the addon and the MCP server are out of sync, features may fail or behave unexpectedly.
  1. Run uvx blender-mcp install-addon to install the latest addon
  2. In Blender, disable and re-enable the Blender MCP addon, or restart Blender
Only run one instance of the Blender MCP 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.
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.
Restart both Claude Desktop (or your MCP client) and the Blender MCP server. This resolves a surprising number of transient connection and state issues.