🧊 Blender MCP

Model Context Protocol (MCP) Server & Addon para Integração do Blender 3D com Modelos de Linguagem (LLMs)

Permite que assistentes de IA (Claude Desktop, Cursor, LM Studio, Continue, Ollama e clientes MCP personalizados) controlem e automatizem fluxos de trabalho no Blender 3D em tempo real através do Model Context Protocol (MCP).

Funcionalidades • Arquitetura • Instalação • Clientes MCP • Segurança • Documentação

🚀 Funcionalidades

• Controle Espacial Completo: Criação, modificação, transformação, rotação, escala e deleção de objetos 3D no Blender.

• Engenharia e Impressão 3D:

  • Geração paramétrica de fixadores mecânicos (parafusos ISO, porcas, arruelas, furos roscados).

  • Análise estrutural, cálculo de volume, centro de massa e área de superfície.

  • Verificação de espessura de paredes finas e análise de overhangs para manufatura aditiva.

  • Reparo automático de malhas não-estanches (non-manifold) e geração de cascas estanques.

• Materiais e Shading:

  • Suporte completo a shaders procedurais e redes de nós (Principled BSDF).

  • Integração com provedores de PBR: Poly Haven, AmbientCG e Sketchfab.

• Automação de Estúdio e Render:

  • Configuração automática de estúdio para fotografia de produtos (ciclorama, iluminação de 3 pontos, softboxes).

  • Captura e inspeção de viewport em tempo real com feedback multimodal para o modelo.

• Barra de Status Integrada:

  • Indicador de status compacto e elegante no rodapé do Blender com ação de alternância rápida (Start / Stop com um clique).

• Servidor WebUI Embutido:

  • Visualizador 3D em tempo real via browser para inspeção remota da cena.

• Execução Segura de Código:

  • Sandbox de execução com circuit breaker, timeout configurável, rate limiting e tokens de autenticação.

Related MCP server: BlenderMCP

🏛 Arquitetura

O sistema é composto por duas partes sincronizadas via socket TCP de baixa latência:

flowchart LR
    subgraph Client ["Cliente MCP"]
        A["Assistente IA<br/>(Cursor, Claude Desktop, LM Studio)"]
    end

    subgraph Bridge ["MCP Bridge Server"]
        B["FastMCP Server<br/>(src/blender_mcp/server.py)"]
    end

    subgraph BlenderApp ["Blender 3D Application"]
        C["Addon Socket Server<br/>(addon/server.py)"]
        D["Router & Handlers<br/>(addon/core/ & addon/handlers/)"]
        E["bpy / Scene Graph"]
    end

    A <== MCP Protocol (stdio / SSE) ==> B
    B <== TCP Socket (127.0.0.1:9876) ==> C
    C --> D
    D --> E

1. Blender Addon (addon/):

   • Roda internamente no processo do Blender.

   • Escuta comandos JSON em porta TCP local (padrão: 9876).

   • Roteia as operações para a thread principal do Blender via bpy.app.timers.

2. MCP Server (src/blender_mcp/):

   • Implementa a especificação oficial do Model Context Protocol (FastMCP).

   • Traduz tool calls de IA em comandos estruturados para o addon no Blender.

📦 Instalação & Configuração

Pré-requisitos

• Blender 4.2 LTS ou superior (compatível com o sistema moderno de Extensões).

• Python 3.10+.

• uv (gerenciador de ambiente e pacotes ultra-rápido).

1. Clonar o Repositório

git clone https://github.com/yuri-schmaltz/mcp_blender.git
cd mcp_blender

2. Sincronizar Dependências com uv

uv sync --extra gui --extra test

3. Instalar o Addon no Blender

1. No Blender, abra Edit > Preferences > Add-ons.

2. Clique no menu superior direito (ícone de engrenagem) e selecione Install from Disk....

3. Selecione o arquivo addon.py ou instale como extensão apontando para a pasta raiz do repositório.

4. Habilite o addon Blender MCP.

5. Na barra de status inferior (ou no painel lateral 3D View > Sidebar > MCP), clique no ícone/botão Start Server.

🤖 Configuração de Clientes MCP

Cursor

Adicione a configuração em .cursor/mcp.json ou nas configurações globais:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "blender-mcp"],
      "cwd": "/caminho/absoluto/para/mcp_blender"
    }
  }
}

Claude Desktop

Edite o arquivo claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "blender-mcp"],
      "cwd": "/caminho/absoluto/para/mcp_blender"
    }
  }
}

LM Studio

1. Abra Settings → Developer → Model Context Protocol (MCP).

2. Adicione um novo servidor:

   • Command: uv

   • Arguments: run blender-mcp

   • Working Directory: Diretório raiz do projeto.

⚙️ Variáveis de Ambiente & Configuração

🛡️ Segurança

Consulte SECURITY.md para a política detalhada de segurança e o modelo de ameaças.

• Isolamento de Loopback: Por padrão, o servidor recusa conexões com bind público (0.0.0.0).

• Circuit Breaker: Proteção contra saturação de chamadas ou travamentos no loop de eventos do Blender.

• Cap de Payload: Bloqueia payloads gigantescos que possam causar saturação de memória.

🧪 Testes de Qualidade

O projeto possui uma suíte de testes unitários e de integração abrangente:

# Executar a suíte de testes principal (185+ testes)
uv run pytest -m "not visual"

# Executar testes unitários específicos
uv run pytest tests/unit/test_statusbar.py -v

📚 Documentação Técnica

• Arquitetura do Sistema

• Decisões Arquiteturais (ADRs)

• Design System & Interface

• Runbook Operacional

• Guia de Troubleshooting

• Guia de Contribuição

📄 Licença & Autoria

Distribuído sob a licença MIT. Veja LICENSE para mais informações.

• Mantenedor & Desenvolvedor Principal: Yuri Schmaltz