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.
Apoiadores
Todos os apoiadores: Apoie este projeto
Início rápido
Nota: o pacote PyPI
blender-mcpagora émcp-for-blender. Configurações existentes continuam funcionando —uvx blender-mcpainda executa o servidor e nenhuma alteração de configuração é necessária. Novas instalações devem usarmcp-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
- Início rápido
- Recursos
- Premium
- Componentes
- Instalação
- Configuração do Cliente MCP
- Instalando o Addon do Blender
- Atualização (usuários existentes)
- Uso
- Credenciais de API Persistentes
- Solução de Problemas
- Detalhes Técnicos
- Limitações e Considerações de Segurança
- Controle de Telemetria
- Feedback
- Contribuindo
- Aviso Legal
- Histórico de Estrelas
Recursos
| Comunicação bidirecional | Conecte o Claude AI ao Blender através de um servidor baseado em socket |
| Manipulação de objetos | Crie, modifique e exclua objetos 3D no Blender |
| Controle de materiais | Aplique e modifique materiais e cores |
| Verificação visual | Visualizaçõ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ódigo | A IA escreve Python do Blender diretamente |
| Geração de assets e modelos | Assets 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:
- Addon do Blender (
addon.py) — um addon do Blender que cria um servidor socket dentro do Blender para receber e executar comandos - 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) ouwhere uvx(Windows) — e use-o como"command", por exemplo,/opt/homebrew/bin/uvxouC:\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ável | Padrão | Descrição |
|---|---|---|
BLENDER_HOST | localhost | Endereço do host para o servidor socket do Blender |
BLENDER_PORT | 9876 | Número da porta para o servidor socket do Blender |
BLENDER_MCP_SAFE_MODE | off | Defina como 1 para validar scripts antes de executá-los no Blender (veja abaixo) |
BLENDER_MCP_APPS | auto | Defina 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_FORMS | auto | Defina 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
localhosta menos que você esteja em uma rede confiável, e prefira um túnel SSH em vez de apontar--host/BLENDER_HOSTpara 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:

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
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.jsonna 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.
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-pathslista as pastas de addons do Blender detectadas. Substitua o destino comBLENDERMCP_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
@latestna primeira vez: lançamentos anteriores a 2.1.7 não têm o comandoupdate, 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;
updateeinstall-addonsão o que realmente gravam. A captura de trajetória ainda funciona em addons mais antigos carregados via um fallbackexecute_code.
Uso
Iniciando a Conexão

- No Blender, vá para a barra lateral da View 3D (pressione N se não estiver visível)
- Encontre a aba MCP for Blender
- Ative as caixas de seleção que deseja usar (veja mais em Capacidades abaixo)
- Clique em Conectar ao Claude
- 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.
![]()
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:
| Ferramenta | Para que serve |
|---|---|
execute_blender_code | Executar Python no seu Blender ativo |
look | Ver 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_info | Resumo compacto da cena, uma linha por objeto com os campos que você escolher (posicionamento, materiais, topologia, pesos, ...); aprofunde com root ou query |
generate_3d | Uma chamada para gerar e importar um modelo com Tripo, Hunyuan3D ou Hyper3D Rodin. Geradores premium são preferidos automaticamente |
search_assets / import_asset | Poly Haven HDRIs, texturas e modelos, Sketchfab modelos, Poly Pizza modelos low-poly |
get_addon_status | Versão do Blender, versão do addon e quais bibliotecas e geradores estão ativados |
disable_telemetry, record_trajectory_feedback | Controles 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á:
| Conta | Serviço que o addon chama | Região | Alternância na barra lateral |
|---|---|---|---|
| China continental (cloud.tencent.com) | AI3D 3.0 (ai3d, versão 2025-05-13) | ap-guangzhou | deixe Conta internacional (Pro) desativada (padrão) |
| Internacional (tencentcloud.com), Hunyuan-to-3D (Professional) | hunyuan, versão 2023-09-01, PBR habilitado | ap-singapore | marque 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.
- Obtenha uma chave de API gratuita em poly.pizza/settings/api
- Na barra lateral da View 3D, marque Usar ativos do Poly Pizza
- 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:
| Prompt | Demonstraçã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 dela | Assistir |
| "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
| Problema | Correção |
|---|---|
| Problemas de conexão | Certifique-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 limite | Tente simplificar suas solicitações ou dividi-las em etapas menores. |
| O Blender congela durante um download do Poly Haven | Os 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 Cloudflare | static.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
typee umparamsopcional - Respostas são objetos JSON com um
statuseresultoumessage
Limitações e Considerações de Segurança
Aviso: A ferramenta
execute_blender_codepermite 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
Se o MCP for Blender é útil para você, considere dar uma estrela no repositório