BlenderMCP

Conecta o Blender ao Claude AI por meio do Model Context Protocol (MCP), permitindo interação e controle diretos para modelagem 3D assistida por prompt, criação e manipulação de cenas.

Documentação

MCP para Blender

Conecte o Blender a qualquer LLM

anteriormente blender-mcp — o pacote PyPI agora é mcp-for-blender. Configurações existentes continuam funcionando; nenhuma alteração de configuração é necessária. Leia mais

Aviso: Esta é uma integração de terceiros e não foi feita pelo Blender

Modelagem 3D assistida por prompt, criação e manipulação de cenas — impulsionada por IA.

PyPI Downloads Discord Website Sponsor PyPI Version License: MIT

ahujasid%2Fblender-mcp | Trendshift


Apoiadores

CodeRabbit Guillermo Rauch

Todos os apoiadores: Apoie este projeto


Início rápido

Nota: o pacote PyPI blender-mcp agora é mcp-for-blender. Configurações existentes continuam funcionando — uvx blender-mcp ainda executa o servidor e nenhuma alteração de configuração é necessária. Novas instalações devem usar mcp-for-blender. O que mudou e por quê

Um único comando configura seus aplicativos de IA e o addon do Blender:

macOS / Linux

curl -LsSf https://www.mcp-for-blender.com/install.sh | sh

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://www.mcp-for-blender.com/install.ps1 | iex"

Já tem uv? Execute uvx mcp-for-blender setup em vez disso.

Ele instala o uv se necessário, encontra os clientes MCP na sua máquina (Claude Desktop, Claude Code, Codex, Cursor, VS Code, Devin Desktop/Windsurf, OpenCode, Antigravity) e permite que você escolha quais configurar. Em seguida, instala o addon do Blender e o ativa. Sua configuração existente é mantida: ele apenas adiciona uma entrada blender e salva um .bak de cada arquivo que altera.

Depois, feche e reabra completamente seu aplicativo de IA (no Windows, feche pela bandeja do sistema), abra o Blender e peça para ele construir algo. O addon inicia seu servidor quando o Blender abre.

Configuração manual, caso a configuração automática não funcione

Três etapas: instale o uv, aponte seu cliente MCP para o servidor e instale o addon do Blender.

1. Instale o uv

# macOS
brew install uv

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

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

Aviso: Não prossiga antes de instalar o uv. Use o instalador oficial — não pip install uv.

2. Adicione o servidor MCP ao seu cliente

Claude Desktop — Configurações → Desenvolvedor → Editar Configuração
{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["mcp-for-blender"]
        }
    }
}
Claude Code
claude mcp add blender uvx mcp-for-blender
Codex
codex mcp add blender -- uvx mcp-for-blender
Cursor / VS Code / OpenCode / Antigravity

Consulte Configuração do Cliente MCP abaixo para instruções por cliente e botões de instalação com um clique.

3. Instale o addon do Blender

uvx mcp-for-blender install-addon

Depois, no Blender: Editar → Preferências → Add-ons → ative Interface: MCP para Blender.

4. Conecte

O addon inicia seu servidor quando o Blender abre. Para verificar, pressione N no viewport 3D → abra a aba MCP para Blender (clique em Iniciar Servidor MCP se não estiver em execução). É isso — peça ao Claude para construir algo.

Nota: Execute apenas uma instância do servidor MCP (ou Cursor ou Claude Desktop), não ambos.


Sumário


Recursos

Comunicação bidirecionalConecte o Claude AI ao Blender através de um servidor baseado em socket
Manipulação de objetosCrie, modifique e exclua objetos 3D no Blender
Controle de materiaisAplique e modifique materiais e cores
Verificação visualVisualizações multiângulo, câmera, wireframe, raio-X e tiras de animação, além de renders, para que a IA verifique seu próprio trabalho
Execução de códigoA IA escreve Python do Blender diretamente
Geração de assets e modelosAssets Poly Haven, modelos Sketchfab, modelos low-poly Poly Pizza e modelos 3D gerados por IA via Tripo, Hyper3D Rodin e Hunyuan3D

Premium

Gere modelos 3D por IA (Hunyuan3D, Tripo, Hyper3D Rodin) diretamente no Blender sem trazer suas próprias chaves de API. Mais detalhes

Componentes

O sistema consiste em dois componentes principais:

  1. Addon do Blender (addon.py) — um addon do Blender que cria um servidor socket dentro do Blender para receber e executar comandos
  2. Servidor MCP (src/blender_mcp/server.py) — um servidor Python que implementa o Model Context Protocol e conecta-se ao addon do Blender

Instalação

Configuração automática

A maneira mais rápida é o instalador de uma linha. Ele instala o uv, configura seus clientes MCP e instala e ativa o addon do Blender:

# macOS / Linux
curl -LsSf https://www.mcp-for-blender.com/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://www.mcp-for-blender.com/install.ps1 | iex"

Já tem uv? Execute uvx mcp-for-blender setup em vez disso. Consulte Início rápido para saber o que ele altera. O restante desta seção cobre a configuração manual.

Pré-requisitos

  • Blender 3.0 ou mais recente
  • Python 3.10 ou mais recente
  • uv gerenciador de pacotes
Instalando uv, por plataforma

macOS

brew install uv

Windows

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Depois, adicione o uv ao caminho do usuário no Windows (talvez seja necessário reiniciar o Claude Desktop depois):

$localBin = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User")

Linux

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

Ele é instalado em ~/.local/bin — abra um novo shell para que esteja no seu PATH.

Caso contrário, as instruções de instalação estão no site deles: Instalar uv

Em todos os sistemas operacionais, use o instalador oficial do uv acima — não pip install uv, que pode não criar o comando uvx e pode ocultar o uv dentro de um ambiente que seu cliente não consegue ver.

Aviso: Não prossiga antes de instalar o uv.

Faça seu cliente encontrar o uvx

Clientes MCP iniciados a partir de uma GUI (Claude Desktop, Cursor, VS Code pelo Dock/Menu Iniciar) não herdam o PATH do seu terminal, então um "command": "uvx" simples pode falhar com spawn uvx ENOENT mesmo que uvx funcione no seu terminal. Se isso acontecer:

  • Encontre o caminho completo do uvx — which uvx (macOS/Linux) ou where uvx (Windows) — e use-o como "command", por exemplo, /opt/homebrew/bin/uvx ou C:\Users\<you>\.local\bin\uvx.exe.
  • No Windows, você pode alternativamente envolvê-lo: "command": "cmd", "args": ["/c", "uvx", "mcp-for-blender"].
  • Após qualquer alteração de PATH ou configuração, feche e reinicie completamente o cliente (Windows: feche pela bandeja do sistema, não apenas pela janela; macOS: Cmd+Q).

Fixar a versão do Python

Evite conflitos de conda / pyenv / versão.

O uv escolhe qual Python executa o servidor. Em máquinas com conda (base autoativado), pyenv ou asdf — ou com uma versão mais recente do CPython para a qual algumas dependências ainda não têm wheels — o uv pode selecionar um interpretador que faça a instalação falhar. Fixe o Python 3.11 e prefira interpretadores gerenciados pelo uv para evitar usar o que estiver no seu PATH:

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["--python", "3.11", "mcp-for-blender"],
            "env": { "UV_PYTHON_PREFERENCE": "only-managed" }
        }
    }
}

--python 3.11 ainda satisfaz o requires-python >=3.10 deste pacote, e UV_PYTHON_PREFERENCE=only-managed impede que o uv selecione conda, pyenv, asdf ou o Python do sistema primeiro. (O .python-version do repositório é apenas uma dica para contribuidores e não afeta o uvx.)

Se uma tentativa falha anterior continuar se repetindo após uma correção, limpe o cache:

uv cache clean mcp-for-blender blender-mcp && uvx --refresh mcp-for-blender

Instalar sem uv

Em máquinas restritas, você pode pular o uvx completamente com pipx e depois apontar seu cliente para o comando instalado:

pipx install mcp-for-blender
pipx ensurepath          # then restart your shell / client

Use o caminho absoluto resultante como "command" (encontre-o com which mcp-for-blender / where mcp-for-blender) e omita args.

Executar com Docker

Você pode executar o servidor MCP em um contêiner em vez de instalá-lo. O Blender em si continua rodando na sua máquina — o contêiner apenas hospeda o servidor MCP, que se conecta ao addon do Blender.

Construa a imagem a partir da raiz do repositório:

docker build -t mcp-for-blender .

Depois, aponte seu cliente MCP para ela (a flag -i é obrigatória — o servidor fala com o cliente via stdin/stdout):

{
    "mcpServers": {
        "blender": {
            "command": "docker",
            "args": ["run", "-i", "--rm", "mcp-for-blender"]
        }
    }
}

A imagem usa como padrão BLENDER_HOST=host.docker.internal, que alcança o Blender do host imediatamente com Docker Desktop em macOS e Windows.

No Linux, host.docker.internal não existe e o addon só escuta em localhost, então use rede do host em vez disso:

{
    "mcpServers": {
        "blender": {
            "command": "docker",
            "args": ["run", "-i", "--rm", "--network=host", "-e", "BLENDER_HOST=localhost", "mcp-for-blender"]
        }
    }
}

Para ativar o modo seguro no contêiner, adicione "-e", "BLENDER_MCP_SAFE_MODE=1" a args.

Variáveis de Ambiente

As seguintes variáveis de ambiente podem ser usadas para configurar a conexão com o Blender:

VariávelPadrãoDescrição
BLENDER_HOSTlocalhostEndereço do host para o servidor socket do Blender
BLENDER_PORT9876Número da porta para o servidor socket do Blender
BLENDER_MCP_SAFE_MODEoffDefina como 1 para validar scripts antes de executá-los no Blender (veja abaixo)
BLENDER_MCP_APPSautoDefina como 1 para forçar o aplicativo de viewport inline para clientes que suportam MCP Apps sem anunciá-lo (o plugin Codex define isso)
BLENDER_MCP_OPENAI_FORMSautoDefina como 1 para forçar os seletores de assets com miniaturas (o plugin Codex define isso)

Exemplo:

export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876

Você também pode passar a conexão como flags de CLI, que têm precedência sobre as variáveis de ambiente. Isso é útil para executar várias instâncias do Blender lado a lado, já que cada entrada de cliente MCP pode apontar para uma porta diferente com argumentos simples em vez de variáveis de ambiente:

uvx mcp-for-blender --port 9877

Em uma configuração de cliente MCP, isso significa uma segunda entrada que difere apenas em args:

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

Cada instância precisa de sua própria porta definida no painel do addon do Blender para corresponder.

Nota: o servidor socket do addon não tem autenticação ou criptografia, então qualquer pessoa que possa alcançar essa porta pode executar Python dentro do Blender. Mantenha-o em localhost a menos que você esteja em uma rede confiável, e prefira um túnel SSH em vez de apontar --host/BLENDER_HOST para uma máquina remota diretamente.

Modo seguro

Por padrão, a IA pode executar qualquer código Python no Blender. Defina BLENDER_MCP_SAFE_MODE=1 para verificar cada script antes de executá-lo e bloquear código arriscado — coisas como ler ou escrever arquivos diretamente, executar outros programas, acessar a rede ou instalar código que continua rodando após o script terminar. O trabalho normal do Blender (modelagem, materiais, renderização, salvar, importar/exportar) continua funcionando. Scripts bloqueados são enviados de volta à IA com o motivo, para que ela possa tentar novamente com uma versão corrigida.


Configuração do Cliente MCP

Claude for Desktop

Assista ao vídeo de instruções de configuração (supondo que você já tenha instalado o uv)

Vá para Claude → Configurações → Desenvolvedor → Editar Config → claude_desktop_config.json e inclua o seguinte:

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

Use a CLI do Claude Code para adicionar o MCP para o servidor Blender:

claude mcp add blender uvx mcp-for-blender

Codex

A CLI do Codex, o aplicativo de desktop e a extensão de IDE compartilham o mesmo arquivo de configuração (~/.codex/config.toml), então configurar o servidor uma vez cobre todos os três.

Plugin Codex (recomendado)

O plugin adiciona uma viewport ao vivo inline no chat (clique em um objeto para anexá-lo à sua próxima mensagem), seletores de miniaturas para Poly Haven, Sketchfab e Poly Pizza, e menções @ para objetos de cena, materiais e coleções. Ele ainda não está no diretório de plugins do Codex, então adicione-o a partir deste repositório:

git clone https://github.com/ahujasid/blender-mcp.git
codex plugin marketplace add ./blender-mcp/integrations/codex

Em seguida, reinicie o Codex, instale MCP for Blender no diretório de plugins e peça para usar o MCP for Blender no chat. Quando estiver em execução, a viewport abre em um painel lateral ao lado da conversa:

MCP for Blender plugin in the Codex app, showing the live viewport beside the chat

Servidor MCP simples

Registre o servidor com a CLI do Codex:

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

Ou adicione manualmente em ~/.codex/config.toml (ou $CODEX_HOME/config.toml):

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

Ou no aplicativo de desktop Codex: Configurações → Servidores MCP → Adicionar servidor → nomeie-o como blender, escolha STDIO, insira uvx mcp-for-blender como o comando, depois Salvar e reinicie. Se o aplicativo não conseguir encontrar uvx, use o caminho completo — veja Faça seu cliente encontrar uvx.

Verifique se foi registrado com codex mcp list — o servidor blender deve aparecer como habilitado. As ferramentas ficam disponíveis na próxima vez que você iniciar o Codex.

Para definir variáveis de ambiente (por exemplo, um host/porta do Blender não padrão), passe flags --env KEY=VALUE para codex mcp add, ou adicione-as no arquivo de configuração:

[mcp_servers.blender]
command = "uvx"
args = ["mcp-for-blender"]
env = { BLENDER_HOST = "localhost", BLENDER_PORT = "9876" }

Cursor

Install MCP Server

macOS — vá para Configurações → MCP e cole o seguinte:

  • Para usar como servidor global, use o botão "adicionar novo servidor MCP global" e cole
  • Para usar como servidor específico do projeto, crie .cursor/mcp.json na raiz do projeto e cole
{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": [
                "mcp-for-blender"
            ]
        }
    }
}

Windows — vá para Configurações → MCP → Adicionar Servidor, adicione um novo servidor com as seguintes configurações:

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

Vídeo de configuração do Cursor

Nota: Execute apenas uma instância do servidor MCP (ou no Cursor ou no Claude Desktop), não ambos.

Visual Studio Code

Pré-requisitos: Certifique-se de ter o Visual Studio Code instalado antes de continuar.

Install in VS Code

OpenCode

{
  "mcp": {
    "blender-mcp": {
      "type": "local",
      "command": ["uvx", "mcp-for-blender"],
      "enabled": true,
      "environment": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }
    }
  }
}

Antigravity

{
  "mcpServers": {
    "blender-mcp": {
      "command": "uvx",
      "args": ["mcp-for-blender"],
      "env": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }
    }
  }
}

Instalando o Addon do Blender

uvx mcp-for-blender setup (veja Início Rápido) faz tudo isso, incluindo habilitar o addon. Os passos abaixo são para fazer manualmente.

1. Recomendado — a partir de um terminal, execute:

uvx mcp-for-blender install-addon

Isso copia o addon para a pasta de addons do seu Blender como blender_mcp.py. Ele imprime onde gravou e mantém um .bak de qualquer arquivo que substituir.

Opcional: uvx mcp-for-blender addon-paths lista as pastas de addons do Blender detectadas. Substitua o destino com BLENDERMCP_ADDONS_DIR=/path/to/scripts/addons.

2. Abra o Blender

3. Vá para Editar → Preferências → Add-ons

4. Habilite Interface: MCP for Blender (pesquise "MCP for Blender"). Se ainda não aparecer, clique em Instalar… e selecione o blender_mcp.py / addon.py copiado, ou reinicie o Blender.

5. Alternativa manual — se o comando acima não encontrar sua instalação do Blender, ou se você preferir fazer manualmente: baixe addon.py deste repositório → no Blender, Editar → Preferências → Add-ons → Instalar… → selecione o addon.py baixado → habilite-o.

Em seguida, abra a aba MCP for Blender na barra lateral do Blender (pressione N na viewport 3D) e clique em Iniciar Servidor MCP. Veja Iniciando a Conexão abaixo.

Atualizando (usuários existentes)

Para novos usuários, vá direto para Início Rápido. Para usuários existentes, veja abaixo.

1. Execute:

uvx mcp-for-blender@latest update

Isso atualiza o servidor MCP (atualizando a cópia em cache do uv, ou atualizando um uv tool install) e cada cópia instalada do addon do Blender, mantendo um .bak de cada arquivo que substituir. Ele nunca faz downgrade de um addon mais novo que o lançamento e deixa intacta uma cópia que você editou localmente. Adicione --dry-run para ver o que mudaria primeiro.

Use @latest na primeira vez: lançamentos anteriores a 2.1.7 não têm o comando update, e o uvx pode ainda ter um desses em cache.

2. Reinicie seu cliente MCP (Claude Desktop, Cursor, ...) para que ele inicie o novo servidor.

3. No Blender: reinicie-o, ou Preferências → Add-ons → desative e reative Interface: MCP for Blender, depois clique em Iniciar Servidor MCP novamente.

Se um cliente ainda estiver configurado com o antigo nome de pacote blender-mcp, update avisa; uvx mcp-for-blender setup faz a troca.

Nota: o servidor MCP nunca modifica os arquivos do addon do Blender por conta própria. Quando inicia, ele verifica se o addon instalado está atrás da cópia incluída e registra como atualizar; update e install-addon são o que realmente gravam. A captura de trajetória ainda funciona em addons mais antigos carregados via um fallback execute_code.


Uso

Iniciando a Conexão

MCP for Blender in the sidebar

  1. No Blender, vá para a barra lateral da View 3D (pressione N se não estiver visível)
  2. Encontre a aba MCP for Blender
  3. Ative as caixas de seleção que deseja usar (veja mais em Capacidades abaixo)
  4. Clique em Conectar ao Claude
  5. Certifique-se de que o servidor MCP está em execução no seu terminal

Usando com Claude

Depois que o arquivo de configuração for definido no Claude e o addon estiver em execução no Blender, você verá um ícone de martelo com ferramentas para MCP for Blender.

MCP for Blender in the sidebar

Capacidades

A IA escreve o Python do Blender por conta própria para modelagem, layout, materiais, animação, rigging e retopologia. O MCP adiciona o que o Python não consegue fazer sozinho, como nove ferramentas:

FerramentaPara que serve
execute_blender_codeExecutar Python no seu Blender ativo
lookVer o resultado do viewport, camera, angles (folha multi-view com enquadramento automático, qualquer direção) ou frames (tira de animação), desenhado solid, material, rendered, wireframe ou xray; ou mostrar um render ou arquivo de imagem
get_scene_infoResumo compacto da cena, uma linha por objeto com os campos que você escolher (posicionamento, materiais, topologia, pesos, ...); aprofunde com root ou query
generate_3dUma chamada para gerar e importar um modelo com Tripo, Hunyuan3D ou Hyper3D Rodin. Geradores premium são preferidos automaticamente
search_assets / import_assetPoly Haven HDRIs, texturas e modelos, Sketchfab modelos, Poly Pizza modelos low-poly
get_addon_statusVersão do Blender, versão do addon e quais bibliotecas e geradores estão ativados
disable_telemetry, record_trajectory_feedbackControles de coleta de dados

Hunyuan3D no Tencent Cloud (modo API oficial)

Qual serviço do Tencent Cloud o addon deve chamar depende de onde sua conta está:

ContaServiço que o addon chamaRegiãoAlternância na barra lateral
China continental (cloud.tencent.com)AI3D 3.0 (ai3d, versão 2025-05-13)ap-guangzhoudeixe Conta internacional (Pro) desativada (padrão)
Internacional (tencentcloud.com), Hunyuan-to-3D (Professional)hunyuan, versão 2023-09-01, PBR habilitadoap-singaporemarque Conta internacional (Pro)

Credenciais internacionais enviadas ao endpoint da China continental falham com AuthFailure.SignatureFailure ou ResourceUnavailable, então marque a alternância quando seu SecretId/SecretKey vierem de tencentcloud.com. A alternância fica em Tencent Hunyuan 3D → API oficial na barra lateral.

Poly Haven

Poly Haven publica cerca de 2.400 HDRIs, texturas e modelos, todos CC0 e gratuitos, financiados por doações em vez de venda dos ativos. Não há chave de API, nem conta, nem limite de taxa que valha a pena se preocupar.

Na barra lateral da View 3D, marque Poly Haven. Essa é toda a configuração.

Exemplo prático:

"Ilumine a cena com um HDRI de tarde nublada e coloque uma textura de metal enferrujado na parede"

Claude chama search_assets(source="polyhaven", query="overcast afternoon", asset_type="hdris"), que entende a intenção em vez de combinar palavras-chave — "sofá" encontra sofás, e funciona em qualquer idioma. previews=3 anexa miniaturas dos melhores resultados antes de gastar a largura de banda, e import_asset(source="polyhaven", id="...", asset_type="textures", apply_to=["Wall"]) baixa uma textura e a aplica em uma única chamada.

As buscas também podem filtrar por caminho de categoria ou por atributos como clima e hora do dia para HDRIs, ou uso de superfície e condição para texturas; um atributo desconhecido gera erro com os válidos.

Os modelos são importados do .blend, que é o arquivo que o artista criou — as versões glTF, FBX e USD são geradas a partir dele e perdem detalhes de material. As texturas constroem um material Principled a partir dos mapas que o alimentam e pulam os reempacotamentos e convenções alternativas que ninguém lê. Os HDRIs são empacotados no arquivo, então a iluminação sobrevive ao salvar e reabrir em outro lugar, e chegam em um novo mundo em vez de sobrescrever um que você construiu.

Licença e atribuição: todo ativo do Poly Haven é CC0. Você nunca precisa dar crédito a ninguém, por nada, comercial ou não. Os termos da API pedem que o software construído sobre a API ao vivo deixe claro de onde vêm os ativos, então as respostas de busca e importação nomeiam a fonte e vinculam a página do ativo. Na importação, polyhaven_id, polyhaven_url, polyhaven_authors, polyhaven_resolution e polyhaven_licence são gravados nos objetos, materiais, imagens e mundo importados como propriedades personalizadas, para que quem abrir o .blend depois ainda possa encontrar o ativo e o artista que o criou.

Poly Pizza

Poly Pizza hospeda cerca de 10.600 modelos low-poly gratuitos, incluindo o arquivo resgatado do Google Poly. É a melhor fonte para ativos de jogos estilizados: cada modelo é um único .glb autocontido, e a geometria é muito mais leve que a do Sketchfab.

  1. Obtenha uma chave de API gratuita em poly.pizza/settings/api
  2. Na barra lateral da View 3D, marque Usar ativos do Poly Pizza
  3. Cole a chave no campo Chave de API que aparece (ou armazene-a permanentemente em Editar → Preferências → Add-ons → MCP for Blender)

Exemplo prático:

"Pesquise no Poly Pizza por uma cadeira low-poly sob licença CC0 e importe uma com 1 metro de altura"

Claude chama search_assets(source="polypizza", query="chair", licence="CC0"), que retorna cada correspondência com sua licença e contagem de triângulos, depois import_asset(source="polypizza", id="...", target_size=1.0).

Você também pode filtrar por categoria ("Animals", "Furniture & Decor", "Transport", "Nature", "Buildings", "People & Characters", "Food & Drink", "Weapons", "Clutter", "Objects", "Scenes & Levels", "Other") ou pedir apenas modelos animados. Atribuição: cerca de 69% do catálogo do Poly Pizza é CC-BY, o que exige que você credite o criador onde quer que o modelo apareça. Na importação, a linha de crédito pré-formatada é gravada em cada objeto raiz importado como a propriedade personalizada polypizza_attribution (junto com polypizza_id e polypizza_licence), então ela é salva no seu .blend e sobrevive à sessão. Filtre com licence="CC0" se preferir usar modelos que não exigem crédito.

Exemplos de Comandos

Aqui estão alguns exemplos do que você pode pedir ao Claude para fazer:

PromptDemonstração
"Crie uma cena low poly em uma masmorra, com um dragão guardando um pote de ouro"Assistir
"Crie uma vibe de praia usando HDRIs, texturas e modelos como rochas e vegetação do Poly Haven"Assistir
Dê uma imagem de referência e crie uma cena do Blender a partir delaAssistir
"Obtenha informações sobre a cena atual e faça um esboço threejs a partir dela"Assistir
"Gere um modelo 3D de um gnomo de jardim através do Hyper3D"
"Preencha esta sala com móveis low-poly do Poly Pizza"
"Deixe este carro vermelho e metálico"
"Crie uma esfera e coloque-a acima do cubo"
"Deixe a iluminação como a de um estúdio"
"Aponte a câmera para a cena e deixe-a isométrica"

Credenciais de API Persistentes

O MCP para Blender suporta credenciais persistentes via Preferências do Add-on do Blender:

Editar → Preferências → Add-ons → MCP for Blender

Você pode armazenar esses valores lá para que eles sobrevivam aos reinícios do Blender:

  • Chave de API do Sketchfab
  • Chave de API do Poly Pizza
  • Chave de API do Hyper3D
  • Hunyuan3D SecretId / SecretKey
  • URL da API do Hunyuan3D

Para configurações headless ou CI, as credenciais também podem ser injetadas por variáveis de ambiente:

Variável
BLENDERMCP_SKETCHFAB_API_KEY
BLENDERMCP_POLYPIZZA_API_KEY
BLENDERMCP_HYPER3D_API_KEY
BLENDERMCP_HUNYUAN3D_SECRET_ID
BLENDERMCP_HUNYUAN3D_SECRET_KEY
BLENDERMCP_HUNYUAN3D_API_URL

Solução de Problemas

ProblemaCorreção
Problemas de conexãoCertifique-se de que o servidor do add-on do Blender esteja em execução e que o servidor MCP esteja configurado no Claude. Não execute o comando uvx no terminal. Às vezes, o primeiro comando não passa, mas depois disso começa a funcionar.
Erros de tempo limiteTente simplificar suas solicitações ou dividi-las em etapas menores.
O Blender congela durante um download do Poly HavenOs ativos são baixados na thread principal do Blender, então a interface para de responder até que a transferência termine. O tamanho do arquivo cresce aproximadamente quatro vezes por etapa de resolução, então peça 1k ou 2k, a menos que o ativo seja mantido próximo à câmera.
O download do Poly Pizza falha com um desafio Cloudflarestatic.poly.pizza está atrás de proteção contra bots e bloqueia IPs de datacenter, VPN e nuvem. Sua chave de API está ok — o CDN nunca a vê. Tente novamente de uma conexão normal, ou baixe o .glb manualmente e use Arquivo → Importar → glTF 2.0.
Você já tentou desligar e ligar de novo?Se você ainda estiver tendo erros de conexão, tente reiniciar tanto o Claude quanto o servidor do Blender.

Detalhes Técnicos

Protocolo de Comunicação

O sistema usa um protocolo simples baseado em JSON sobre sockets TCP:

  • Comandos são enviados como objetos JSON com um type e um params opcional
  • Respostas são objetos JSON com um status e result ou message

Limitações e Considerações de Segurança

Aviso: A ferramenta execute_blender_code permite executar código Python arbitrário no Blender, o que pode ser poderoso, mas potencialmente perigoso. Use com cautela em ambientes de produção. SEMPRE salve seu trabalho antes de usá-la.

  • O Poly Haven exige o download de modelos, texturas e imagens HDRI. Se você não quiser usá-lo, desative-o na caixa de seleção no Blender.
  • Operações complexas podem precisar ser divididas em etapas menores.

Controle de Telemetria

A telemetria é opt-in. A coleta do seu conteúdo está desativada por padrão e permanece desativada até que você a ative explicitamente.

O que é coletado por padrão (sem opt-in): um registro mínimo de uso anônimo para que eu possa contar usuários ativos e ver quais ferramentas são usadas — um ID de instalação gerado aleatoriamente, um ID de sessão, o nome da ferramenta, se ela teve sucesso, quanto tempo levou, as versões do MCP for Blender e do Blender, seu sistema operacional e um carimbo de data/hora.

Nunca coletado sem opt-in: seus prompts, código gerado, capturas de tela da viewport, dados da cena e etapas de trajetória.

Para fazer opt-in — vá em Editar → Preferências → Add-ons → MCP for Blender e marque a caixa de consentimento de telemetria. Alguns clientes MCP também oferecerão um prompt de opt-in único no início de uma conversa. O opt-in adiciona prompts, código gerado, capturas de tela e dados de trajetória ao que é coletado; consulte os Termos e Condições para detalhes. Você pode desativá-lo novamente no mesmo lugar a qualquer momento.

Para desativar a telemetria completamente, incluindo o registro mínimo de uso anônimo, defina uma variável de ambiente:

DISABLE_TELEMETRY=true uvx mcp-for-blender

Ou adicione-a à sua configuração MCP:

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

Os dados de telemetria não estão vinculados ao seu nome ou conta. Eles podem ser usados para melhorar o MCP for Blender, para pesquisa e para treinar modelos de IA.

Detalhes completos sobre o que é coletado e a licença que você concede ao fazer opt-in estão em TERMS_AND_CONDITIONS.md.


Feedback

Estamos ativamente buscando feedback sobre o MCP for Blender. Se você tiver opiniões, compartilhe-as aqui.

Se você tiver um feedback mais detalhado, pode agendar uma chamada conosco aqui — daremos crédito a você no projeto.

Junte-se à Comunidade

Dê feedback, inspire-se e construa em cima do MCP: Discord

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Aviso Legal

Esta é uma integração de terceiros e não foi feita pelo Blender. Feito por Siddharth.


Histórico de Estrelas

Star History Chart

Se o MCP for Blender é útil para você, considere dar uma estrela no repositório