Blender MCP: configuração do addon para Claude, Codex e ChatGPT

Você digita "monte uma poltrona low-poly com estrutura de nogueira" em uma janela de chat e, alguns segundos depois, a forma aparece na sua viewport do Blender. Isso é o Blender MCP em ação, e a configuração leva cerca de dez minutos quando você sabe onde cada peça entra. Há um porém: o projeto mudou de nome. O pacote no PyPI agora é mcp-for-blender, o nome antigo blender-mcp sobrevive apenas como um wrapper de compatibilidade, e muitos tutoriais ainda mostram os comandos antigos. Este artigo usa os nomes atuais e traz os passos exatos para o Claude e o Codex, além de uma análise honesta sobre o ChatGPT, que não consegue se conectar diretamente a esse tipo de servidor. Você também verá correções para os erros que bloqueiam a maioria das primeiras tentativas.

Como o Blender MCP funciona de fato

Três pequenos programas passam mensagens ao longo de uma cadeia, e quando você consegue visualizar essa cadeia, cada mensagem de erro começa a fazer sentido.

Três peças em movimento

1. O addon do Blender. Ele roda dentro do Blender e abre um servidor de socket local, em localhost:9876 por padrão. É a única peça que pode mexer na sua cena.
2. O servidor MCP. Um pequeno programa em Python iniciado com uvx mcp-for-blender. Ele fala MCP com seu cliente de IA via stdio e encaminha cada comando para o socket do addon.
3. O cliente de IA. Claude Desktop, Claude Code, Codex, Cursor ou VS Code. O cliente inicia o servidor MCP sozinho, então você nunca precisa deixar um terminal aberto para ele.

Na configuração descrita no README, o addon é instalado uma vez e todos os clientes iniciam o mesmo servidor. Isso significa que você pode trocar de cliente sem reinstalar nada.

💡 A ordem importa. Se o addon não estiver conectado, o servidor MCP ainda inicia e o cliente ainda lista as ferramentas, mas cada chamada falha. Peça ao assistente para executar get_addon_status primeiro; ele informa o lado do addon na conexão.

O que as ferramentas podem fazer

execute_blender_code faz a maior parte do trabalho. O assistente escreve Python para Blender, o addon o executa e a cena muda. Todas as outras ferramentas são uma conveniência construída em torno dessa, e por isso vale a pena ler os hábitos de segurança no final.

Antes de instalar qualquer coisa

Qual cliente escolher? Claude Desktop é o mais amigável se você quer uma janela de chat ao lado da viewport. Claude Code e Codex ficam no terminal, o que combina com quem já escreve scripts para Blender e quer que o assistente leia arquivos e edite scripts junto com a cena. Cursor e VS Code fazem sentido quando seu trabalho no Blender está dentro de um projeto de código maior. O ChatGPT é a exceção, e ganha uma seção própria abaixo.

Instale o uv primeiro, porque uvx vem com ele:

# macOS
brew install uv

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Copiar prompt

Abra um novo terminal depois e execute uvx --version. Se o comando não for encontrado, seu shell ainda não carregou o novo PATH.

Instale o addon do Blender

Tutoriais mais antigos pedem para você baixar um arquivo addon.py e instalá-lo a partir do disco nas Preferências. O README atual substitui isso por um único comando.

Instalação com um comando

uvx mcp-for-blender install-addon

Copiar prompt

Isso coloca o addon onde o Blender consegue encontrá-lo. Se o Blender já estava aberto, reinicie-o para que a lista de complementos seja atualizada.

Ative nas Preferências

1. No Blender, abra Editar → Preferências → Complementos.
2. Pesquise por MCP.
3. Marque a caixa ao lado de Interface: MCP for Blender.

O Blender lembra da configuração, então você faz isso só uma vez.

Conecte pela barra lateral

Passe o cursor sobre a viewport 3D e pressione N. Uma aba chamada MCP for Blender aparece. Clique em Conectar ao Claude. O rótulo menciona o Claude, mas o que você está ligando é o socket local na porta 9876. O README não mostra um botão separado para outros clientes, então usuários do Codex e do Cursor pressionam esse mesmo botão.

Duas variáveis de ambiente podem mudar os padrões do servidor MCP: BLENDER_HOST (padrão localhost) e BLENDER_PORT (padrão 9876). Não mexa nelas, a menos que outro programa na sua máquina já use essa porta.

Conecte o Claude

Configuração JSON do Claude Desktop

Abra Configurações → Developer → Edit Config e adicione esta entrada em claude_desktop_config.json:

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["mcp-for-blender"]
    }
  }
}

Copiar prompt

Feche o Claude Desktop por completo e reabra. As ferramentas do Blender devem aparecer em um novo chat. Para testá-las, pergunte: "Chame get_addon_status e me diga o que o Blender responde." Uma resposta limpa, em vez de um erro, significa que toda a cadeia funciona: cliente, servidor, socket e addon. O Cursor usa o mesmo JSON em Configurações → MCP. No Windows, no VS Code ou no Cursor, o README envolve o comando com cmd: defina "command": "cmd" e "args": ["/c", "uvx", "mcp-for-blender"].

Claude Code em uma linha

claude mcp add blender uvx mcp-for-blender
claude mcp list

Copiar prompt

A segunda linha confirma que o servidor está registrado. Dentro de uma sessão, /mcp mostra se ele realmente se conectou.

Conecte o Codex e o ChatGPT

Codex: CLI ou config.toml

O Codex inicia servidores stdio assim como o Claude. Um comando o registra:

codex mcp add blender -- uvx mcp-for-blender

Copiar prompt

Os dois traços importam: tudo depois deles é o comando que o Codex vai executar. Se preferir editar a configuração, adicione isto em ~/.codex/config.toml, ou em um .codex/config.toml no nível do projeto em um projeto confiável:

[mcp_servers.blender]
command = "uvx"
args = ["mcp-for-blender"]

Copiar prompt

Registre o servidor uma vez, inicie codex na pasta do seu projeto e envie o mesmo teste get_addon_status antes de qualquer outra coisa.

O ChatGPT precisa de uma URL remota

Aqui está a parte que a maioria dos tutoriais pula. O ChatGPT se conecta a servidores MCP pelo modo desenvolvedor, nos planos Plus, Pro, Business, Enterprise e Edu, e espera um endpoint HTTPS remoto. Ele não inicia comandos locais como uvx. O servidor do Blender é local e só usa stdio, e o README não menciona o ChatGPT, então não existe uma configuração de copiar e colar.

⚠️ Um túnel colocaria uma ferramenta que pode executar Python arbitrário na sua máquina atrás de uma URL pública, e o próprio README avisa que o socket do Blender não tem autenticação. Evite esse caminho, a menos que você adicione autenticação adequada na frente e desfaça o túnel ao fim de cada sessão.

Seus primeiros prompts

Comece com algo simples e confira a conexão antes de pedir algo ambicioso. Informe logo no início a sua versão do Blender (Ajuda → Sobre), porque a API Python do Blender muda entre versões e o modelo escreve scripts melhores quando sabe qual versão ele deve usar.

O ciclo que funciona é construa uma etapa, observe, corrija. O README avisa que operações complexas podem precisar ser divididas em etapas menores, e um modelo que confere a viewport após cada mudança tem muito menos chance de se desviar do que um que escreve um script de 200 linhas às cegas.

Uma sessão saudável funciona assim. O assistente chama get_scene_info para ver o que já existe, escreve um script que cria uma armação, um assento e um encosto, chama look, percebe que as pernas estão finas demais em relação ao assento e as ajusta antes que você diga qualquer coisa. Quando algo falha, cole o texto do erro de volta no chat. Os erros de Python do Blender são específicos, e os assistentes costumam corrigi-los rápido quando conseguem ler o traceback.

Dê nome a tudo. Peça uma coleção por asset e um nome claro para cada objeto. Uma cena com Cube.047 é difícil de editar pelo chat, e uma cena com armchair_leg_front_left é fácil.

Assets sem modelagem. search_assets e import_asset acessam várias fontes. Poly Haven oferece HDRIs, texturas e modelos CC0 gratuitos, sem cadastro. Sketchfab e Poly Pizza exigem credenciais. Para o que ainda não existe, generate_3d pode chamar Hunyuan3D, Tripo ou Hyper3D Rodin.

Corrigindo erros comuns

Conexão recusada na porta 9876

Siga esta lista na ordem:

1. O addon está ativado, e você clicou em Conectar ao Claude na barra lateral depois do último reinício do Blender?
2. Outro programa está usando a porta 9876? Verifique com lsof -i :9876 no macOS e no Linux, ou netstat -an | findstr 9876 no Windows.
3. Você alterou BLENDER_PORT ou BLENDER_HOST em apenas um lugar? Os dois lados precisam estar iguais.
4. get_addon_status responde? Se responder, a conexão está boa e o problema está no seu prompt, não na configuração.

Ferramentas ausentes ou configuração antiga em uso

• Reinicie o cliente. Servidores MCP carregam na inicialização, então uma edição na configuração não faz efeito até você fechar e reabrir o app.
• PATH errado. Apps de desktop muitas vezes não herdam o PATH do seu shell. Execute which uvx no macOS e no Linux, ou where uvx no Windows, e coloque o caminho completo em "command".
• Nome antigo. Uma configuração que ainda diz blender-mcp continua funcionando pelo wrapper de compatibilidade, mas troque para mcp-for-blender para não depender do wrapper.
• Addon desatualizado. Se você instalou addon.py manualmente meses atrás, execute uvx mcp-for-blender install-addon de novo para atualizá-lo.

Hábitos de segurança que salvam suas cenas

• Salve antes de cada sessão. O README diz para sempre salvar seu trabalho antes de usar a ferramenta de código, e um único script ruim pode mudar muita coisa em um passo só.
• Mantenha em localhost. O socket não tem autenticação, então não o exponha a uma rede em que você não confia.
• Confira o modo seguro. O README lista uma configuração BLENDER_MCP_SAFE_MODE que vem desligada por padrão. Leia o que ela restringe e ative-a para cenas que você não consegue recriar.
• Salve incrementalmente. Use Arquivo → Salvar incremental entre mudanças grandes para poder voltar uma versão, não dez.

Teste seus próprios assets no PicassoIA

O Blender MCP fica mais forte quando o assistente parte de um bom material bruto: uma imagem de referência limpa, uma malha bruta, um script rascunhado por um modelo forte. PicassoIA tem os três no navegador.

Escolha o modelo certo

Os três modelos de linguagem aparecem para tarefas de programação, então você pode rascunhar um script de Blender ali e colá-lo na aba Scripting quando não quiser que um assistente conduza a sessão.

Como usar o Hunyuan 3D no PicassoIA

Hunyuan 3D 3.1 transforma uma imagem ou uma descrição de texto em um modelo 3D texturizado. Este é o caminho da ideia até o Blender:

1. Crie a entrada. Gere um objeto em um fundo liso com Seedream 4.5 ou GPT Image 2. Mantenha texto fora do quadro e deixe o objeto ocupar mais da metade dele. Você também pode pular a imagem e escrever um prompt, mas o modelo aceita uma imagem ou um prompt, nunca os dois.
2. Abra a página do modelo e envie a imagem. JPG, PNG, JPEG e WebP funcionam, com até 6 MB e 5000 px por lado.
3. Escolha generate_type. Normal retorna um modelo texturizado. Geometry retorna uma malha branca simples, útil quando você quer texturizá-la dentro do Blender.
4. Defina enable_pbr. Vem desligado por padrão. Ative para materiais que reagem corretamente à luz.
5. Reduza face_count. O padrão é 500.000 faces, o que é pesado para uma cena com muitos objetos. Tente 50.000 a 100.000 em uma primeira passada.
6. Execute e espere. O exemplo na página do modelo levou cerca de 145 segundos.
7. Baixe e importe. O exemplo publicado é um .glb, então use Arquivo → Importar → glTF 2.0 no Blender e peça ao Claude ou ao Codex para corrigir a escala, a origem e os materiais.

💡 Se a sua fonte for uma foto de um objeto real, execute Rodin na mesma imagem e compare as duas malhas antes de se decidir por uma.

Sua vez de construir

Configure o Blender MCP uma vez e todos os projetos seguintes começam mais rápido. Abra o Picasso IA, gere uma imagem de referência do objeto que você quer, transforme-a em malha com o Hunyuan 3D 3.1, importe-a e peça ao seu assistente para iluminar e enquadrar. Comece com uma cadeira ou um produto, depois avance para um personagem ou um cômodo inteiro. A primeira cena leva uma tarde. A segunda leva vinte minutos.