Blender MCP · Troubleshooting
Troubleshooting & limits
The most common issues and how to fix them, followed by the honest limits of the product. If yours isn't here, open a support ticket.
The tools say Blender is not connected
Symptom: The client loads the server, but the tools answer that Blender does not respond.
Fix: Open Blender and check that the Synthetic Blender MCP add-on is enabled (Edit → Preferences → Add-ons). If it is not in the list, install it as shown in the install guide.
Blender stops responding for a while
Symptom: Blender's window freezes while a tool runs, for example during a render or a simulation.
Fix: This is expected: the tools run on Blender's main thread, so a long render keeps the window busy until it finishes. Wait for it; if a tool timed out meanwhile, ask your AI client to check the scene before trying again.
Invalid license error
Symptom: The tools answer that the license is missing or invalid, or the client logs say BLENDER_MCP_LICENSE is not set.
Fix: The license in your config doesn't match the one on /dashboard/licenses. Recopy it — check for leading/trailing spaces when you pasted it into the JSON — and restart the MCP client.
The tools stopped working after an update
Symptom: The server updated itself and the tools now fail when they talk to Blender.
Fix: An update can bring a new version of the add-on. Install it again from Blender's Preferences (see the install guide) and restart Blender.
The client says Node.js was not found
Symptom: Your MCP client cannot start the server and its logs mention node.
Fix: Run Synthetic Setup again (it adds Node.js for your MCP clients when it is missing), or install Node.js (LTS) from nodejs.org and restart the client.
Limits
What Blender MCP does not do, or has not been tested with. We say it here so you know before you install it.
- Verified on Windows with Blender 5.1.2 and 5.2.2 LTS. macOS is in beta: it has not been fully tested and may have errors. Linux and other versions of Blender have not been verified yet.
- Blender has to be open, with the add-on enabled, whenever your AI client runs a tool. Work with one Blender window open at a time.
- The tools run on Blender's main thread: during a long render or simulation Blender does not respond until it finishes. If a tool times out, work Blender had already started may still finish.
- Poly Haven's download service is for non-commercial use unless you have their free commercial license. ambientCG assets (CC0) and files you load from your own disk have no such restriction.
- The tools that run Python or any operator inside Blender can do anything Blender can, including deleting data. Keep your work saved and let your AI client ask you before anything irreversible.
- The add-on is free software (GNU GPL version 3), as Blender requires for add-ons. The MCP server is Synthetic's own software and needs your free license key.
If none of this helps
Open a ticket at your support dashboard with: (1) your Blender version, (2) your MCP client and its version, (3) the client's logs when it tries to launch the server, and (4) the config snippet you pasted (without the license key). You can also ask in our Discord.