Blender MCP · Solução de problemas
Solução de problemas e limites
Os problemas mais comuns e como resolvê-los, seguidos pelas limitações honestas do produto. Se o seu problema não estiver aqui, abra um ticket de suporte.
As ferramentas dizem que o Blender não está conectado
Sintoma: O cliente carrega o servidor, mas as ferramentas informam que o Blender não está respondendo.
Solução: Abra o Blender e verifique se o add-on Synthetic Blender MCP está ativado (Editar → Preferências → Add-ons). Se ele não estiver na lista, instale-o conforme mostrado em o guia de instalação.
O Blender deixa de responder por um tempo
Sintoma: A janela do Blender congela enquanto uma ferramenta está em execução, por exemplo durante uma renderização ou uma simulação.
Solução: Isso é esperado: as ferramentas rodam na thread principal do Blender, então uma renderização longa mantém a janela ocupada até terminar. Aguarde; se uma ferramenta expirou nesse meio tempo, peça ao seu cliente de IA para verificar a cena antes de tentar novamente.
Erro de licença inválida
Sintoma: As ferramentas respondem que a licença está ausente ou é inválida, ou os logs do cliente indicam que BLENDER_MCP_LICENSE não foi configurado.
Solução: A licença na sua configuração não corresponde à que está em /dashboard/licenses. Copie-a novamente — verifique se há espaços no início ou no fim ao colá‑la no JSON — e reinicie o cliente MCP.
As ferramentas pararam de funcionar após uma atualização
Sintoma: O servidor se atualizou e as ferramentas agora falham ao se comunicar com o Blender.
Solução: An update can bring a new version of the add-on. Install it again from Blender's Preferences (see o guia de instalação) and restart Blender.
O cliente informa que o Node.js não foi encontrado
Sintoma: Seu cliente MCP não consegue iniciar o servidor e os logs mencionam node.
Solução: Execute o Synthetic Setup novamente (ele adiciona o Node.js para seus clientes MCP quando está ausente) ou instale o Node.js (LTS) de nodejs.org e reinicie o cliente.
Limites
O que o Blender MCP não faz, ou com o que não foi testado. Dizemos isso aqui para você saber antes de instalar.
- Verificado no Windows com Blender 5.1.2 e 5.2.2 LTS. O macOS está em beta: não foi totalmente testado e pode ter erros. Linux e outras versões do Blender ainda não foram verificados.
- O Blender deve estar aberto, com o add-on ativado, sempre que seu cliente de IA executar uma ferramenta. Trabalhe com apenas uma janela do Blender aberta por vez.
- As ferramentas rodam na thread principal do Blender: durante uma renderização ou simulação longa, o Blender não responderá até que ela termine. Se uma ferramenta expirar por timeout, o trabalho que o Blender já iniciou poderá ser concluído.
- O serviço de download do Poly Haven é para uso não comercial, a menos que você possua a licença comercial gratuita deles. Ativos do ambientCG (CC0) e arquivos que você carrega do seu próprio disco não possuem essa restrição.
- As ferramentas que executam Python ou qualquer operador dentro do Blender podem fazer tudo o que o Blender é capaz, incluindo deletar dados. Mantenha seu trabalho salvo e deixe que seu cliente de IA pergunte a você antes de qualquer ação irreversível.
- O add-on é um software livre (GNU GPL versão 3), conforme exigido pelo Blender para add-ons. O servidor MCP é um software próprio da Synthetic e requer a sua chave de licença gratuita.
Se nada disso ajudar
Abra um ticket em seu painel de suporte com: (1) sua versão do Blender, (2) seu cliente MCP e a versão dele, (3) os logs do cliente ao tentar iniciar o servidor e (4) o trecho da configuração que você colou (sem a chave de licença). Você também pode perguntar no nosso Discord.