Bonsai MCP

Um servidor MCP que integra suporte a modelos IFC usando Bonsai BIM (Blender) e IfcOpenShell.

GitHub
64
Experimente este MCPPatrocinado

Documentação

Bonsai-mcp - Integração do Model Context Protocol para IFC através do IfcOpenShell e Blender

Bonsai-mcp é um fork do BlenderMCP que estende a funcionalidade original com suporte dedicado para modelos IFC (Industry Foundation Classes) através do Bonsai. Esta integração é uma plataforma para permitir que LLMs leiam e modifiquem arquivos IFC.

Recursos

  • Funcionalidade específica para IFC: Consulte modelos IFC, analise estruturas espaciais, examine elementos de construção e extraia quantidades

  • Onze ferramentas IFC incluídas: Inspecione informações do projeto, liste entidades, examine propriedades, explore a estrutura espacial, analise relacionamentos e muito mais

  • Pensamento Sequencial: Inclui a ferramenta de pensamento sequencial do modelcontextprotocol/servers para resolução estruturada de problemas

  • Ferramenta Executar Código da implementação original do BlenderMCP: Crie e modifique objetos, aplique materiais e execute código Python no Blender

Componentes

O sistema consiste em dois componentes principais:

  1. Addon do Blender (addon.py): Um addon do Blender que cria um servidor de socket dentro do Blender para receber e executar comandos, incluindo operações específicas de IFC

  2. Servidor MCP (tools.py): Um servidor Python que implementa o Model Context Protocol e se conecta ao addon do Blender

Instalação - Através das Configurações do Cliente MCP

Pré-requisitos

  • Blender 4.0 ou mais recente

  • Python 3.12 ou mais recente

  • Gerenciador de pacotes uv

  • Addon Bonsai BIM para Blender (para funcionalidade IFC)

Instalando o uv:

Mac:


brew  install  uv

Windows:


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

set  Path=C:\Users\[username]\.local\bin;%Path%

Para outras plataformas, consulte o guia de instalação do uv.

Clonar o repositório


git  clone  https://github.com/JotaDeRodriguez/Bonsai_mcp

Integração com Claude for Desktop

Edite seu arquivo claude_desktop_config.json (Claude > Configurações > Desenvolvedor > Editar Configuração) para incluir:

{
    "mcpServers": {
        "Bonsai-mcp": {
            "command": "uv",
            "args": [
              "--directory",
              "\\your\\path\\to\\Bonsai_mcp",
              "run",
              "tools.py"
          ]
        }
    }
}

Instalação via Docker

O repositório vem com um Dockerfile que torna a implantação simples e consistente em diferentes ambientes.

Início Rápido

# Clone the repository
git clone https://github.com/JotaDeRodriguez/Bonsai_mcp
cd Bonsai_mcp

# Build the Docker image
docker build -t bonsai_mcp .

# Run the container
docker run -p 8000:8000 --name bonsai_mcp bonsai_mcp

Uma vez em execução, o contêiner exporá as ferramentas MCP como APIs REST/OpenAPI em http://localhost:8000.

  • Para verificar sua instalação, abra seu navegador e navegue até
  • http://localhost:8000/docs
  • Você verá a interface Swagger UI com todos os endpoints disponíveis
  • Teste um endpoint clicando nele, depois clique em "Try it out" e "Execute"

Conectando ao Open WebUI ou Outros Clientes de API

Para conectar esta API ao Open WebUI:

  1. No Open WebUI, vá para Configurações > Gerenciar Servidores de Ferramentas
  2. Adicione uma nova conexão com:
  • URL: http://localhost:8000
  • Caminho para a especificação OpenAPI: /openapi.json
  • Autenticação: Nenhuma (a menos que configurado de outra forma)

Variáveis de Ambiente

O contêiner Docker aceita várias variáveis de ambiente para personalizar seu comportamento:

# Example with custom settings
docker run -p 8000:8000 \
  -e BLENDER_HOST=host.docker.internal \
  -e BLENDER_PORT=9876 \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  --name bonsai_mcp bonsai_mcp

Instalando o Addon do Blender

  1. Baixe o arquivo addon.py deste repositório

  2. Abra o Blender

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

  4. Clique em "Instalar..." e selecione o arquivo addon.py

  5. Ative o addon marcando a caixa ao lado de "Interface: Blender MCP - IFC"

Uso

Iniciando a Conexão

  1. No Blender, vá para a barra lateral da Visualização 3D (pressione N se não estiver visível)

  2. Encontre a aba "Blender MCP - IFC"

  3. Clique em "Conectar ao Claude"

  4. Certifique-se de que o servidor MCP está em execução

Usando com o Claude

Uma vez conectado, você verá um ícone de martelo na interface do Claude com ferramentas para a integração Blender MCP IFC.

Ferramentas IFC

Este repositório inclui múltiplas ferramentas específicas de IFC que permitem consulta e manipulação abrangente de modelos IFC:

get_ifc_project_info: Recupera informações básicas sobre o projeto IFC, incluindo nome, descrição e contagens de diferentes tipos de entidades. Exemplo: "Qual é a informação básica sobre este projeto IFC?"

list_ifc_entities: Lista entidades IFC de um tipo específico (paredes, portas, espaços, etc.) com opções para limitar resultados e filtrar por seleção. Exemplo: "Liste todas as paredes neste modelo IFC" ou "Mostre-me as janelas neste edifício"

get_ifc_properties: Recupera todas as propriedades de uma entidade IFC específica pelo seu GlobalId ou de objetos atualmente selecionados. Exemplo: "Quais são as propriedades desta parede com ID 1Dvrgv7Tf5IfTEapMkwDQY?"

get_ifc_spatial_structure: Obtém a hierarquia espacial do modelo IFC (terreno, edifício, pavimentos, espaços). Exemplo: "Mostre-me a estrutura espacial deste edifício"

get_ifc_relationships: Recupera todos os relacionamentos para uma entidade IFC específica. Exemplo: "Quais são os relacionamentos da porta de entrada?"

get_selected_ifc_entities: Obtém informações sobre entidades IFC correspondentes aos objetos atualmente selecionados na interface do Blender. Exemplo: "Fale-me sobre os elementos que selecionei no Blender"

get_user_view: Captura a viewport atual do Blender como uma imagem, permitindo a visualização do modelo a partir da perspectiva do usuário. Exemplo: "Mostre-me o que o usuário está vendo atualmente no Blender"

export_ifc_data: Exporta dados IFC para um arquivo JSON ou CSV estruturado, com opções para filtrar por tipo de entidade ou nível do edifício. Exemplo: "Exporte todos os dados de paredes para um arquivo CSV"

place_ifc_object: Cria e posiciona um elemento IFC no modelo em coordenadas especificadas com rotação opcional. Exemplo: "Coloque uma porta nas coordenadas X:10, Y:5, Z:0 com rotação de 90 graus"

get_ifc_quantities: Calcule e obtenha quantidades (m2, m3, etc.) para elementos IFC, com opções para filtrar por tipo de entidade ou selecionados. Exemplo: "Dê-me a área de todas as paredes no edifício usando a ferramenta get_ifc_quantities"

get_ifc_total_structure: Recupera a estrutura hierárquica completa do modelo IFC, incluindo elementos espaciais (Projeto, Terreno, Edifício, Pavimentos) e todos os elementos de construção dentro de cada contêiner espacial. Esta visão abrangente combina hierarquia espacial com elementos de construção, essencial para gerar relatórios completos e orçamentos. Exemplo: "Mostre-me a estrutura completa deste modelo IFC, incluindo todos os elementos de construção organizados por andar"

export_drawing_png: Exporta desenhos 2D e 3D como imagens PNG de alta resolução com parâmetros de resolução e visualização personalizáveis. Cria vistas de planta ortográficas a partir de cima em deslocamentos de altura especificados. Exemplo: "Gere um PNG de planta baixa para o térreo na resolução 1920x1080"

get_ifc_georeferencing_info: Recupera informações abrangentes de georreferenciamento de arquivos IFC, incluindo sistemas de referência de coordenadas (CRS), conversões de mapa, sistemas de coordenadas mundiais, direção do norte verdadeiro e coordenadas geográficas do terreno. Exemplo: "Quais informações de georreferenciamento estão disponíveis neste modelo IFC?"

georeference_ifc_model: Cria ou atualiza informações de georreferenciamento em modelos IFC, permitindo definir sistemas de referência de coordenadas usando códigos EPSG ou definições de CRS personalizadas, estabelecer conversões de mapa com coordenadas de leste/norte e configurar o posicionamento geográfico do terreno. Exemplo: "Georreferencie este modelo IFC usando EPSG:4326 com coordenadas na latitude 40.7589, longitude -73.9851"

export_bc3_budget: Exporta um arquivo de orçamento BC3 (formato FIEBDC-3/2016) baseado no modelo IFC carregado no Blender. Esta ferramenta cria um orçamento de construção completo extraindo a estrutura espacial IFC, agrupando elementos de construção por tipo e categoria (estrutura, alvenaria, lajes, carpintaria, instalações, mobiliário), atribuindo preços unitários de um banco de dados abrangente e gerando medições detalhadas. Suporta saída em vários idiomas (espanhol/inglês) com codificação adequada para caracteres internacionais. O formato BC3 é o padrão espanhol para orçamentos de construção e estimativa de custos. Exemplo: "Gere um arquivo de orçamento BC3 em espanhol para este modelo de edifício"

Recursos

  • Categorização automática de elementos: Os elementos de construção são automaticamente classificados em categorias:

    • ESTR: Elementos estruturais (vigas, colunas, sapatas, estacas, rampas, escadas)
    • ALB: Alvenaria (paredes)
    • FORG: Lajes e coberturas
    • CARP: Carpintaria (portas, janelas)
    • INST: Instalações (tubulações, conexões, terminais, corrimãos)
    • MOB: Mobiliário

  • Medições precisas:

    • Paredes medidas por NetSideArea (considera aberturas como portas e janelas)
    • Lajes e coberturas medidas por GrossVolume
    • Vigas, colunas e estacas medidas por comprimento (metros)
    • Portas, janelas e mobiliário contados como unidades

  • Suporte a vários idiomas: Gere orçamentos em espanhol ou inglês com codificação de caracteres adequada (windows-1252)

  • Estrutura hierárquica: Os capítulos do orçamento seguem a hierarquia espacial IFC (Projeto → Terreno → Edifício → Pavimento)

  • Banco de dados de preços unitários: Inclui preços unitários abrangentes para elementos de construção comuns, totalmente personalizáveis via arquivos JSON

  • Medições ordenadas: Os elementos dentro de cada categoria são ordenados alfabeticamente para facilitar a revisão

Arquivos de Configuração

A exportação BC3 usa arquivos de configuração JSON externos localizados em resources/bc3_helper_files/:

  • precios_unitarios.json / unit_prices.json: Preços unitários por tipo de elemento IFC
  • spatial_labels_es.json / spatial_labels_en.json: Traduções de elementos espaciais
  • element_categories.json: Mapeamentos de tipo IFC para categoria de orçamento

Esses arquivos podem ser personalizados para adaptar a geração de orçamento às necessidades específicas do projeto ou padrões regionais de preços.

Saída

Os arquivos BC3 são exportados para a pasta exports/ com o formato FIEBDC-3/2016 adequado, incluindo:

  • Estrutura hierárquica completa de capítulos
  • Medições detalhadas para cada elemento
  • Preços unitários e totais
  • Conformidade total com o padrão espanhol de orçamento de construção bc3

Recursos MCP

Esta integração fornece acesso à documentação estruturada através de recursos MCP:

file://table_of_contents.md: Contém o modelo completo de estrutura de relatório técnico para gerar relatórios abrangentes de edifícios. Este recurso fornece um sumário padronizado que pode ser usado como referência ao criar documentação técnica a partir de modelos IFC.

Prompts MCP

O servidor inclui Prompts MCP especializados para geração automatizada de relatórios:

Technical_building_report: Gera relatórios técnicos abrangentes de edifícios baseados em modelos IFC carregados no Blender. Este prompt fornece um fluxo de trabalho estruturado para criar documentação arquitetônica profissional em vários idiomas (inglês, espanhol, francês, alemão, italiano, português). O prompt guia a análise através de extração sistemática de dados do modelo IFC, incluindo estrutura espacial, quantidades, materiais e sistemas de construção, culminando em um relatório técnico completo com desenhos e visualizações 3D.

Executar Código no Blender

Recurso legado da implementação MCP original. Permite que o Claude execute código Python arbitrário no Blender. Use com cautela.

Ferramenta de Pensamento Sequencial

Esta integração inclui a ferramenta de Pensamento Sequencial para resolução estruturada de problemas e análise. Ela facilita um processo de pensamento passo a passo que pode ramificar, revisar e se adaptar à medida que a compreensão se aprofunda - perfeito para análise complexa de modelos IFC ou tarefas de planejamento.

Exemplo: "Use pensamento sequencial para analisar a eficiência energética deste edifício com base no modelo IFC"

Exemplos de Comandos

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

  • "Analise este modelo IFC e me diga quantas paredes, portas e janelas ele tem"

  • "Mostre-me a estrutura espacial deste modelo de edifício"

  • "Liste todos os espaços neste modelo IFC e suas propriedades"

  • "Identifique todos os elementos estruturais neste edifício"

  • "Quais são os relacionamentos entre esta parede e outros elementos?"

  • "Gere um relatório das medições do modelo IFC aberto no Blender"

  • "Use pensamento sequencial para criar um plano de manutenção para este edifício com base no modelo IFC"

  • "Gere um arquivo de orçamento BC3 em espanhol para o modelo IFC atual"

  • "Exporte uma estimativa de custo de construção para o formato BC3 com descrições em inglês"

Solução de Problemas

  • Problemas de conexão: Certifique-se de que o servidor do addon do Blender está em execução e que o servidor MCP está configurado no Claude
  • Modelo IFC não carregando: Verifique se você tem o addon Bonsai BIM instalado e se um arquivo IFC está carregado
  • Erros de timeout: Tente simplificar suas solicitações ou dividi-las em etapas menores

Docker:

  • Erros de "Connection refused": Certifique-se de que o Blender está em execução e que o addon está habilitado com o servidor iniciado
  • Problemas de CORS: A API tem CORS habilitado por padrão para todas as origens. Se você encontrar problemas, verifique as configurações de CORS do seu cliente
  • Preocupações com desempenho: Para modelos IFC grandes, as respostas da API podem ser mais lentas. Considere ajustar os timeouts no seu cliente

Detalhes Técnicos

A integração IFC usa o módulo Bonsai BIM para acessar a funcionalidade ifcopenshell dentro do Blender. A comunicação segue o mesmo protocolo baseado em JSON sobre sockets TCP do BlenderMCP original.

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

  • A ferramenta execute_blender_code do projeto original ainda está disponível, permitindo executar código Python arbitrário no Blender. Use com cautela e sempre salve seu trabalho.

  • Modelos IFC complexos podem exigir a divisão das operações em etapas menores.

  • O desempenho das consultas IFC depende do tamanho e da complexidade do modelo.

  • A ferramenta Get User View retorna uma imagem codificada em base64. Certifique-se de que o cliente a suporta.

Contribuições

Este repositório licenciado sob MIT está aberto para ser bifurcado, modificado e usado de qualquer forma. Estou aberto a ideias e colaborações, então não hesite em entrar em contato comigo para contribuições.

Créditos

A FAZER

Integração e testes com mais clientes MCP