> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-for-blender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Blender MCP Connection and Runtime Issues

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

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.

<Accordion title="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
</Accordion>

<Accordion title="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 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
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="Poly Haven erratic behavior">
  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.
</Accordion>

<Accordion title="Poly Pizza download fails with Cloudflare challenge">
  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**
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="Addon version mismatch">
  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
</Accordion>

<Accordion title="Multiple MCP server instances">
  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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="Have you tried turning it off and on again?">
  Restart both Claude Desktop (or your MCP client) and the Blender MCP server. This resolves a surprising number of transient connection and state issues.
</Accordion>