Skip to main content
Glama

🧊 Blender MCP

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

Python 3.10+ Blender 4.2+ License: MIT Protocol: MCP

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

Variável

Padrão

Descrição

BLENDER_HOST

127.0.0.1

Endereço do socket do Blender

BLENDER_PORT

9876

Porta do socket TCP

BLENDER_MCP_TOKEN

(vazio)

Token de autenticação opcional para transporte seguro

BLENDER_MCP_LOG_LEVEL

INFO

Nível de log (DEBUG, INFO, WARNING, ERROR)

BLENDER_MCP_LOG_HANDLER

console

Destino do log (console ou file)

BLENDER_MCP_CODE_TIMEOUT

30.0

Timeout em segundos para execução de scripts arbitrários

BLENDER_MCP_MAX_PAYLOAD

4194304

Tamanho máximo de payload recebido via TCP (4 MiB)


🛡️ 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


📄 Licença & Autoria

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Connects Blender to AI through the Model Context Protocol to enable prompt-assisted 3D modeling and scene manipulation. It supports object creation, material control, and arbitrary Python code execution directly within the Blender environment.
      22
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects Blender to AI assistants through the Model Context Protocol, enabling direct AI control of 3D modeling, scene creation, and manipulation via natural language.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Connects Blender 3D to AI assistants via the Model Context Protocol, enabling natural language driven 3D scene creation, manipulation, and rendering.
      15
      MIT