Blender MCP · 故障排除
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
症状： The client loads the server, but the tools answer that Blender does not respond.
修复： 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
症状： Blender's window freezes while a tool runs, for example during a render or a simulation.
修复： 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
症状： The tools answer that the license is missing or invalid, or the client logs say BLENDER_MCP_LICENSE is not set.
修复： 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
症状： The server updated itself and the tools now fail when they talk to Blender.
修复： 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
症状： Your MCP client cannot start the server and its logs mention node.
修复： 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
Blender MCP 做不到的事，或尚未测试过的情况。我们在此说明，方便您在安装前了解。
- 已在 Windows 上的 Blender 5.1.2 和 5.2.2 LTS 版本中通过验证。macOS 为测试版：尚未经过完整测试，可能存在错误。Linux 及其他 Blender 版本尚未验证。
- 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.
- 该插件是自由软件（GNU GPL 第 3 版），这是 Blender 对插件的要求。MCP 服务器是 Synthetic 自己的软件，需要您的免费许可证密钥。
If none of this helps
Open a ticket at 您的支持控制台 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.