"Blender MCP" geralmente se refere ao MCP for Blender, um projeto de código aberto de Siddharth Ahuja que permite a um agente de IA controlar uma cópia do Blender que está aberta. Ele se chamava blender-mcp até novembro de 2026, e a maioria dos tutoriais ainda usa esse nome. Com ele conectado, Claude Code, Codex, Cursor ou Claude Desktop conseguem criar e editar objetos, aplicar materiais, olhar o viewport e exportar arquivos, tudo a partir de um prompt de chat.
Este guia explica o que ele é, como instalar no Claude Code e no Codex, e um exemplo completo: um agente monta no Blender um prop low-poly para jogo, exporta como GLB, o arquivo é comprimido com o glTF-Transform e o three.js o carrega em um jogo de navegador. Conferimos cada comando com o README do projeto e a documentação oficial em 21 de novembro de 2026. Nós mesmos não rodamos a instalação nem o exemplo, então trate os resultados descritos abaixo como o que a documentação diz que deve acontecer.
O que é o Blender MCP
MCP (Model Context Protocol) é um jeito padrão de dar a um agente de IA ferramentas que atuam em outro programa. O MCP for Blender tem duas partes:
- Um add-on do Blender que abre um servidor de socket dentro do Blender (porta 9876 por padrão) e executa os comandos que recebe.
- Um servidor MCP (o pacote Python
mcp-for-blender) que seu agente inicia em segundo plano. Ele repassa as chamadas de ferramentas do agente para o add-on.
O agente trabalha principalmente escrevendo Python do Blender e executando no seu arquivo aberto. O README lista nove ferramentas. As que você mais vai ver são execute_blender_code (executa Python no Blender), look (tira vistas do viewport, da câmera ou de vários ângulos para o agente conferir o próprio trabalho), get_scene_info (um resumo da cena) e search_assets / import_asset (trazem modelos, texturas e HDRIs do Poly Haven, Sketchfab e Poly Pizza). Há também o generate_3d, que cria um modelo com Meshy, Tripo, Hunyuan3D ou Hyper3D Rodin.
Ele não é feito pelo Blender. O README abre com "This is a third-party integration and not made by Blender" (é uma integração de terceiros, não feita pelo Blender), e a descrição no GitHub diz "Not affiliated with the official Blender Foundation." (sem afiliação com a Blender Foundation). Tem licença MIT e tinha 35.153 estrelas no GitHub em 21 de novembro de 2026.
O Blender tem, sim, um servidor MCP próprio. O Blender Lab, parte do projeto Blender, publica um menor em projects.blender.org/lab/blender_mcp, documentado em blender.org/lab/mcp-server. O readme o descreve como "deliberately small" (pequeno de propósito). Ele foca na documentação da API Python do Blender, resumos de cena e de arquivos, capturas de tela e execução de código. Exige Blender 5.1 ou mais novo, é GPL-3.0 e estava na v1.0.3 (setembro de 2026). Também está listado no diretório de conectores do Claude como "Blender", feito pelo Blender Lab. Falamos dele em Alternativas.
O que você precisa
- Blender 3.0 ou mais novo para o MCP for Blender (o add-on declara a 3.0 como mínimo).
- Python 3.10 ou mais novo e uv, a ferramenta que roda o servidor com
uvx. O instalador de uma linha abaixo instala o uv para você. - Um agente com suporte a MCP: Claude Code, Codex, Cursor, Claude Desktop, VS Code, OpenCode, Windsurf ou Antigravity, segundo o README.
- Para a parte do jogo: Node.js (para o glTF-Transform) e um projeto three.js.
A instalação rápida (todos os clientes de uma vez)
O caminho recomendado pelo README é um comando que instala o uv, encontra os agentes na sua máquina, deixa você escolher quais configurar e instala e ativa o add-on do Blender. Ele só adiciona uma entrada blender em cada arquivo de configuração e salva uma cópia .bak de cada arquivo que altera.
macOS / Linux:
curl -LsSf https://www.mcp-for-blender.com/install.sh | sh
Windows (PowerShell):
irm https://www.mcp-for-blender.com/install.ps1 | iex
Se você já tem o uv:
uvx mcp-for-blender setup
Passar um script da internet direto para o shell o executa com as permissões do seu usuário. Se prefere não fazer isso, use os passos manuais abaixo, que fazem a mesma coisa peça por peça. De qualquer forma, feche por completo e reabra seu agente depois.
Instalar o Blender MCP no Claude Code
- Instale o uv. O README indica
brew install uvno macOS,curl -LsSf https://astral.sh/uv/install.sh | shno Linux ewinget install --id=astral-sh.uv -eno Windows. Ele avisa para não usarpip install uv, que pode não criar o comandouvx. - Registre o servidor no Claude Code. Este é o comando do README:
claude mcp add blender uvx mcp-for-blender
- Confira. A documentação de MCP do Claude Code cita
claude mcp list(mostra um status como "✔ Connected") eclaude mcp get blender, e o painel/mcpdentro de uma sessão mostra o mesmo.
Por padrão, claude mcp add salva o servidor só para o projeto atual. Adicione --scope user para usar em todos os projetos. A forma geral da documentação coloca o comando do servidor depois de --: claude mcp add [options] <name> -- <command> [args...]. Você precisa do -- se adicionar opções como --scope ou --env.
Para desligar a telemetria anônima de uso do projeto, o README manda definir a variável de ambiente DISABLE_TELEMETRY=true para o servidor. No Claude Code, você a passa com --env antes do --.
Instalar o Blender MCP no Codex
A CLI do Codex, o app desktop do Codex e a extensão de IDE compartilham um único arquivo de configuração, ~/.codex/config.toml, então uma configuração serve para os três.
Servidor MCP simples. O comando do README:
codex mcp add blender -- uvx mcp-for-blender
Ou adicione à mão em ~/.codex/config.toml:
[mcp_servers.blender]
command = "uvx"
args = ["mcp-for-blender"]
Rode codex mcp list e confira se blender aparece como ativado. As ferramentas aparecem na próxima vez que você iniciar o Codex, e /mcp na interface de terminal do Codex lista os servidores ativos. A documentação de MCP do Codex da OpenAI também descreve uma tabela env para variáveis de ambiente, startup_timeout_sec (padrão 10) e tool_timeout_sec (padrão 60). No app desktop, vá em Settings → MCP servers → Add server, dê o nome blender, escolha STDIO e digite uvx mcp-for-blender.
Plugin do Codex. O README recomenda esse caminho para o Codex. Ele adiciona um viewport do Blender ao vivo dentro do chat, seletores com miniaturas para Poly Haven, Sketchfab e Poly Pizza, e menções com @ para objetos da cena. Ainda não está no diretório de plugins do Codex, então você o adiciona a partir do repositório:
git clone https://github.com/ahujasid/blender-mcp.git
codex plugin marketplace add ./blender-mcp/integrations/codex
Depois reinicie o Codex, instale o MCP for Blender pelo diretório de plugins e peça ao Codex para usá-lo.
Cursor e outros
No Cursor, abra Settings → MCP e adicione um servidor global, ou crie .cursor/mcp.json no seu projeto, com:
{
"mcpServers": {
"blender": {
"command": "uvx",
"args": [
"mcp-for-blender"
]
}
}
}
No Windows, o README usa "command": "cmd" com "args": ["/c", "uvx", "mcp-for-blender"]. O README também tem botões de instalação em um clique para Cursor e VS Code, e blocos de configuração para Claude Desktop, OpenCode e Antigravity. Ele diz para rodar só uma cópia do servidor por vez, por exemplo Cursor ou Claude Desktop, mas não os dois.
Conectar o add-on do Blender
O instalador rápido faz isso por você. À mão:
- Rode
uvx mcp-for-blender install-addon. Ele copia o add-on para a pasta de add-ons do Blender comoblender_mcp.py. - No Blender, abra Edit → Preferences → Add-ons e ative Interface: MCP for Blender. Se ele não aparecer, reinicie o Blender ou clique em Install… e escolha o arquivo copiado. Você também pode baixar o
addon.pydo repositório e instalar esse. - No viewport 3D, aperte N para abrir a barra lateral e procure a aba MCP for Blender. O add-on inicia o servidor quando o Blender abre. Se ele não estiver rodando, clique em Start MCP Server.
A aba do add-on é onde você liga recursos opcionais como Poly Haven, Poly Pizza (precisa de uma API key gratuita) e os geradores 3D.
Se o agente não conseguir conectar: confira se o Blender está aberto com o add-on rodando, e não inicie uvx mcp-for-blender você mesmo em um terminal (a tabela de solução de problemas do README diz para não fazer isso). Apps abertos pelo Dock ou pelo menu Iniciar podem não achar o uvx e falhar com spawn uvx ENOENT. Resolva usando como comando o caminho completo que which uvx (macOS/Linux) ou where uvx (Windows) mostra. Se ainda falhar, reinicie o agente e o Blender.
Exemplo completo: um prop low-poly para jogo, do prompt ao three.js
Objetivo: um baú de tesouro para um jogo de navegador, pequeno o bastante para carregar rápido, em um formato que o three.js lê direto. Escrevemos este fluxo a partir da documentação e não o rodamos de ponta a ponta, então os tamanhos de arquivo e os resultados exatos vão variar.
1. Salve seu arquivo do Blender primeiro
Abra um arquivo novo no Blender e salve (por exemplo chest.blend) antes de o agente começar. O agente altera seu arquivo diretamente, e o próprio aviso do README é sempre salvar seu trabalho antes.
2. Dê o prompt ao agente
No Claude Code ou no Codex, com o Blender aberto e conectado:
Use the Blender MCP tools. In the current scene, build a low-poly treasure chest
for a browser game:
- About 1 m wide, 0.6 m deep, 0.7 m tall, sitting on the ground at z = 0,
origin at the bottom centre.
- A box body and a curved lid made from a half-cylinder with 8 segments,
plus metal bands and a lock plate. Keep it under 1,500 triangles.
- Flat-shaded materials using Principled BSDF base colours only
(dark wood, brass), no image textures.
- Apply all modifiers and transforms, join everything into one object named "Chest".
- Check it with the look tool from several angles and fix anything that
overlaps or floats.
- Then select only "Chest" and export it as a GLB to ./public/models/chest.glb.
Show me each script before you run it.
Algumas escolhas desse prompt importam para jogos. Cores base lisas são exportadas sem problema, porque o exportador glTF pega a cor base do nó Principled BSDF, segundo o manual de glTF do Blender. Um objeto único e unido vira uma única malha no three.js. Colocar a origem na base faz o baú ficar no chão quando você define a posição como y = 0. Um orçamento de triângulos impede o agente de adicionar subdivisão.
3. A etapa de exportação
O agente escreve o Python do Blender. A exportação costuma terminar com uma chamada como esta, que usa os parâmetros documentados na API export_scene do Blender:
import bpy
bpy.ops.export_scene.gltf(
filepath="/path/to/your-game/public/models/chest.glb",
export_format='GLB', # single binary file: mesh, materials and images packed together
use_selection=True, # only the selected "Chest" object
export_apply=True, # apply modifiers on export
export_yup=True, # glTF's +Y up convention, which three.js also uses
)
Leia este script antes de aprovar, como com todo script que o agente executa. Confira se o caminho aponta para dentro do seu projeto e se nada apaga nem sobrescreve arquivos importantes para você.
4. Comprima o GLB com o glTF-Transform
O glTF-Transform é uma ferramenta de linha de comando para otimizar arquivos glTF. Instale e rode optimize. Estes são os comandos do README dele:
npm install --global @gltf-transform/cli
gltf-transform optimize input.glb output.glb --texture-compress webp
Para o nosso baú:
gltf-transform optimize public/models/chest.glb public/models/chest.opt.glb --texture-compress webp
Por padrão, o optimize comprime a geometria com meshopt (--compress meshopt), limita as texturas a 2048 px e achata o grafo da cena. Nosso baú não tem texturas de imagem, então --texture-compress webp não tem o que fazer aqui, mas deixe a opção para props que tenham. Para comprimir só a geometria, o glTF-Transform também tem gltf-transform meshopt input.glb output.glb --level medium.
5. Carregue no three.js
Um arquivo comprimido com meshopt precisa do decodificador meshopt. Sem ele, o GLTFLoader lança "setMeshoptDecoder must be called before loading compressed files". Os imports abaixo são os que o three.js usa nos próprios exemplos:
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
const loader = new GLTFLoader();
loader.setMeshoptDecoder(MeshoptDecoder);
const gltf = await loader.loadAsync('/models/chest.opt.glb');
const chest = gltf.scene;
chest.position.set(0, 0, -3); // origin is at the bottom, so y = 0 puts it on the floor
scene.add(chest);
O Blender trabalha em metros, assim como a maioria das cenas three.js, então o baú deve carregar com cerca de 1 m de largura. Se ele entrar deitado de lado, provavelmente a exportação rodou sem export_yup. Se ficar preto, sua cena precisa de luzes: adicione uma HemisphereLight ou um mapa de ambiente.
6. Itere
Deixe o arquivo do Blender aberto e peça mudanças, como "faça a tampa abrir 40 graus como um objeto separado chamado Lid" ou "adicione uma pilha de ouro dentro". Depois rode a exportação e o comando optimize de novo. Peça ao agente para guardar o script de exportação no seu projeto, assim você tem as mesmas configurações toda vez.
Limites e segurança
- Ele executa qualquer Python dentro do Blender. O aviso do README: "The
execute_blender_codetool allows running arbitrary Python code in Blender, which can be powerful but potentially dangerous." (A ferramentaexecute_blender_codepermite executar código Python arbitrário no Blender, o que pode ser poderoso, mas potencialmente perigoso). O Python no Blender pode ler e escrever qualquer arquivo que sua conta de usuário alcance. Peça ao agente para mostrar os scripts antes de rodar, e leia-os. - Salve seu arquivo antes de cada sessão. O mesmo aviso termina assim: "ALWAYS save your work before using it." (salve SEMPRE seu trabalho antes de usar). Salve versões no caminho (File → Save Incremental).
- Ligue o modo seguro se você não precisa de acesso a arquivos ou à rede. Defina
BLENDER_MCP_SAFE_MODE=1para o servidor. Cada script passa então por uma verificação antes de rodar, e é bloqueado o código que lê ou escreve arquivos diretamente, executa outros programas, usa a rede ou continua rodando depois que o script termina. Modelagem, materiais, renderização, salvamento e importação/exportação continuam funcionando. - Mantenha em localhost. O socket do add-on não tem autenticação nem criptografia. Qualquer pessoa que alcance essa porta pode executar Python no seu Blender. Não o exponha a uma rede em que você não confia.
- Divida trabalhos grandes em etapas. O README diz que operações complexas podem precisar de passos menores, e que timeouts se resolvem simplificando o pedido. Os downloads do Poly Haven rodam na thread principal do Blender, então o Blender trava até terminarem.
- Confira as licenças dos assets. O Poly Haven é CC0. Cerca de 69% do Poly Pizza é CC-BY, que exige crédito. O add-on escreve a linha de crédito nos objetos importados, ou você pode buscar com
licence="CC0". - Telemetria. Por padrão, o servidor envia um registro de uso anônimo: ID de instalação, ID de sessão, nome da ferramenta, sucesso, duração, versões, sistema operacional e carimbo de data e hora. Seus prompts, código, capturas de tela e dados de cena só são coletados se você aceitar.
DISABLE_TELEMETRY=truedesliga tudo.
Alternativas ao Blender MCP
- Blender MCP do Blender Lab: o servidor do próprio Blender. É menor e gira em torno da documentação da API Python, resumos de cena e de arquivos, capturas de tela e execução de código, incluindo um modo em segundo plano para arquivos
.blend. Exige Blender 5.1+ e é GPL-3.0. O wiki dele configura clonando o repositório e rodando comuv --directory .../blender_mcp/mcp run blender-mcp. Escolha-o se você quer o projeto oficial e não precisa de busca de assets nem de geração de modelos por IA. - Blender Agent Skills: 28 skills para Blender 5.2 LTS+ (modelagem, UVs, baking, rigging, animação, otimização, exportação) para Claude Code, Codex, OpenCode, Gemini CLI, Copilot e Cursor. MIT. As skills ensinam o agente a fazer o trabalho. Um servidor MCP dá a ele controle do Blender. Você pode usar os dois.
- blender-game-skills: skills do Claude Code que levam de arte conceitual a assets 3D com rig e prontos para jogo. MIT.
- Modelos prontos. Para props comuns, um modelo grátis costuma ser mais rápido do que gerar um. Veja os GLBs low-poly do Polyfork.
Nossa lista de skills e servidores MCP para fazer jogos cobre os equivalentes para Godot, Unity, Unreal e three.js.
Perguntas frequentes
O Blender MCP é grátis?
Sim. O MCP for Blender tem licença MIT e o add-on é grátis. A página Premium diz que todos os recursos funcionam no plano gratuito e que só a geração 3D é paga. Você pode usar Meshy, Tripo, Hunyuan3D, Hyper3D Rodin ou World Labs com suas próprias API keys, ou comprar o Premium (a partir de $10/mês em 21 de novembro de 2026) para usá-los sem keys. O servidor do Blender Lab é grátis sob GPL-3.0. Você ainda paga a assinatura ou o uso de API do seu agente de IA.
O Blender MCP é seguro?
É tão seguro quanto o código que você deixa ele executar. O agente executa Python dentro do Blender, e esse Python tem o acesso a arquivos do seu usuário. Salve seu trabalho, leia os scripts antes de aprovar, use o modo seguro (BLENDER_MCP_SAFE_MODE=1) e mantenha a porta do add-on em localhost. Instale pelo repositório oficial ou pelo script de instalação do próprio projeto, não por uma cópia que alguém reenviou.
Existe um servidor MCP oficial do Blender?
Sim. O Blender Lab publica um em projects.blender.org/lab/blender_mcp, e o diretório de conectores do Claude o lista como "Blender", feito pelo Blender Lab. O MCP for Blender, mais conhecido (antes blender-mcp), é um projeto de terceiros que não é afiliado à Blender Foundation.
O Blender MCP funciona com o Claude Code?
Sim. Rode claude mcp add blender uvx mcp-for-blender, abra o Blender com o add-on ativado e confira com claude mcp list. O Claude Desktop, em vez disso, é configurado com um bloco JSON em claude_desktop_config.json.
O Blender MCP funciona com o Codex?
Sim. Rode codex mcp add blender -- uvx mcp-for-blender ou adicione [mcp_servers.blender] em ~/.codex/config.toml. O README também oferece um plugin do Codex que mostra um viewport do Blender ao vivo ao lado do chat.
O Blender MCP funciona com o ChatGPT?
O README lista clientes desktop e de programação (Claude Desktop, Claude Code, Codex, Cursor, VS Code, Windsurf, OpenCode, Antigravity), não o app do ChatGPT. O Codex é o agente da OpenAI para isso. O servidor conversa com um Blender rodando no seu próprio computador, então você precisa de um cliente que consiga iniciar um servidor MCP local.
Onde fica a aba do Blender MCP?
No viewport 3D do Blender, aperte N para abrir a barra lateral. A aba se chama MCP for Blender. Se ela não aparecer, ative Interface: MCP for Blender em Edit → Preferences → Add-ons.
Blender MCP ou uma skill do Blender?
Um servidor MCP permite que o agente atue em um Blender ao vivo: criar objetos, olhar o viewport, exportar. Uma skill ensina ao agente fluxos de trabalho e convenções do Blender, o que ajuda tanto se ele depois trabalhar via MCP quanto se rodar o Blender sem interface pela linha de comando. Para assets de jogos, usar os dois funciona bem. O servidor MCP faz a construção, e um pacote de skills como o Blender Agent Skills cobre UVs, otimização e configurações de exportação.
Fontes
Conferidas em 21 de novembro de 2026: README do mcp-for-blender, MCP for Blender Premium, Blender Lab blender_mcp e seu wiki de configuração, documentação de MCP do Claude Code, documentação de MCP do Codex, API export_scene do Blender, manual de glTF 2.0 do Blender, CLI do glTF-Transform, GLTFLoader do three.js.


