Bonsai MCP

Un servidor MCP que integra soporte para modelos IFC utilizando Bonsai BIM (Blender) y IfcOpenShell.

GitHub
64
Prueba este MCPPatrocinado

Documentación

Bonsai-mcp - Integración del Protocolo de Contexto de Modelo para IFC mediante IfcOpenShell y Blender

Bonsai-mcp es un fork de BlenderMCP que amplía la funcionalidad original con soporte dedicado para modelos IFC (Clases de Fundación de la Industria) a través de Bonsai. Esta integración es una plataforma que permite a los LLM leer y modificar archivos IFC.

Características

  • Funcionalidad específica de IFC: Consulta modelos IFC, analiza estructuras espaciales, examina elementos de construcción y extrae cantidades

  • Once herramientas IFC incluidas: Inspecciona información del proyecto, lista entidades, examina propiedades, explora la estructura espacial, analiza relaciones y más

  • Pensamiento Secuencial: Incluye la herramienta de pensamiento secuencial de modelcontextprotocol/servers para la resolución estructurada de problemas

  • Herramienta Ejecutar Código de la implementación original de BlenderMCP: Crea y modifica objetos, aplica materiales y ejecuta código Python en Blender

Componentes

El sistema consta de dos componentes principales:

  1. Complemento de Blender (addon.py): Un complemento de Blender que crea un servidor de sockets dentro de Blender para recibir y ejecutar comandos, incluidas operaciones específicas de IFC

  2. Servidor MCP (tools.py): Un servidor Python que implementa el Protocolo de Contexto de Modelo y se conecta al complemento de Blender

Instalación - Mediante la Configuración del Cliente MCP

Requisitos previos

  • Blender 4.0 o superior

  • Python 3.12 o superior

  • Gestor de paquetes uv

  • Complemento Bonsai BIM para Blender (para la funcionalidad IFC)

Instalación de 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 otras plataformas, consulta la guía de instalación de uv.

Clonar el repositorio


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

Integración con Claude para Desktop

Edita tu archivo claude_desktop_config.json (Claude > Configuración > Desarrollador > Editar Configuración) para incluir:

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

Instalación mediante Docker

El repositorio incluye un Dockerfile que facilita el despliegue de forma simple y consistente en diferentes entornos.

Inicio 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

Una vez en ejecución, el contenedor expondrá las herramientas MCP como API REST/OpenAPI en http://localhost:8000.

  • Para verificar tu instalación, abre tu navegador y navega a
  • http://localhost:8000/docs
  • Verás la interfaz Swagger UI con todos los endpoints disponibles
  • Prueba un endpoint haciendo clic en él, luego haz clic en "Try it out" y "Execute"

Conexión a Open WebUI u Otros Clientes API

Para conectar esta API a Open WebUI:

  1. En Open WebUI, ve a Configuración > Administrar Servidores de Herramientas
  2. Añade una nueva conexión con:
  • URL: http://localhost:8000
  • Ruta al especificación OpenAPI: /openapi.json
  • Autenticación: Ninguna (a menos que se configure de otra manera)

Variables de Entorno

El contenedor Docker acepta varias variables de entorno para personalizar su comportamiento:

# 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

Instalación del Complemento de Blender

  1. Descarga el archivo addon.py de este repositorio

  2. Abre Blender

  3. Ve a Editar > Preferencias > Complementos

  4. Haz clic en "Instalar..." y selecciona el archivo addon.py

  5. Activa el complemento marcando la casilla junto a "Interface: Blender MCP - IFC"

Uso

Iniciar la Conexión

  1. En Blender, ve a la barra lateral de la Vista 3D (pulsa N si no está visible)

  2. Encuentra la pestaña "Blender MCP - IFC"

  3. Haz clic en "Connect to Claude"

  4. Asegúrate de que el servidor MCP esté en ejecución

Uso con Claude

Una vez conectado, verás un icono de martillo en la interfaz de Claude con herramientas para la integración Blender MCP IFC.

Herramientas IFC

Este repositorio incluye múltiples herramientas específicas de IFC que permiten la consulta y manipulación integral de modelos IFC:

get_ifc_project_info: Recupera información básica sobre el proyecto IFC, incluidos nombre, descripción y recuentos de diferentes tipos de entidades. Ejemplo: "¿Cuál es la información básica sobre este proyecto IFC?"

list_ifc_entities: Lista entidades IFC de un tipo específico (muros, puertas, espacios, etc.) con opciones para limitar resultados y filtrar por selección. Ejemplo: "Lista todos los muros de este modelo IFC" o "Muéstrame las ventanas de este edificio"

get_ifc_properties: Recupera todas las propiedades de una entidad IFC específica mediante su GlobalId o de los objetos seleccionados actualmente. Ejemplo: "¿Cuáles son las propiedades de este muro con ID 1Dvrgv7Tf5IfTEapMkwDQY?"

get_ifc_spatial_structure: Obtiene la jerarquía espacial del modelo IFC (sitio, edificio, plantas, espacios). Ejemplo: "Muéstrame la estructura espacial de este edificio"

get_ifc_relationships: Recupera todas las relaciones de una entidad IFC específica. Ejemplo: "¿Cuáles son las relaciones de la puerta de entrada?"

get_selected_ifc_entities: Obtiene información sobre las entidades IFC correspondientes a los objetos seleccionados actualmente en la interfaz de Blender. Ejemplo: "Háblame de los elementos que he seleccionado en Blender"

get_user_view: Captura la ventana gráfica actual de Blender como imagen, permitiendo la visualización del modelo desde la perspectiva del usuario. Ejemplo: "Muéstrame lo que el usuario está viendo actualmente en Blender"

export_ifc_data: Exporta datos IFC a un archivo JSON o CSV estructurado, con opciones para filtrar por tipo de entidad o nivel de edificio. Ejemplo: "Exporta todos los datos de muros a un archivo CSV"

place_ifc_object: Crea y posiciona un elemento IFC en el modelo en coordenadas especificadas con rotación opcional. Ejemplo: "Coloca una puerta en las coordenadas X:10, Y:5, Z:0 con rotación de 90 grados"

get_ifc_quantities: Calcula y obtiene cantidades (m2, m3, etc.) para elementos IFC, con opciones para filtrar por tipo de entidad o elementos seleccionados. Ejemplo: "Dame el área de todos los muros del edificio usando la herramienta get_ifc_quantities"

get_ifc_total_structure: Recupera la estructura jerárquica completa del modelo IFC, incluidos los elementos espaciales (Proyecto, Sitio, Edificio, Plantas) y todos los elementos de construcción dentro de cada contenedor espacial. Esta vista integral combina la jerarquía espacial con los elementos de construcción, esencial para generar informes y presupuestos completos. Ejemplo: "Muéstrame la estructura completa de este modelo IFC, incluidos todos los elementos de construcción organizados por planta"

export_drawing_png: Exporta dibujos 2D y 3D como imágenes PNG de alta resolución con resolución y parámetros de vista personalizables. Crea vistas de planta ortográficas desde arriba en desfases de altura especificados. Ejemplo: "Genera un PNG de plano de planta para la planta baja a resolución 1920x1080"

get_ifc_georeferencing_info: Recupera información completa de georreferenciación de archivos IFC, incluidos sistemas de referencia de coordenadas (CRS), conversiones de mapa, sistemas de coordenadas mundiales, dirección del norte verdadero y coordenadas geográficas del sitio. Ejemplo: "¿Qué información de georreferenciación está disponible en este modelo IFC?"

georeference_ifc_model: Crea o actualiza información de georreferenciación en modelos IFC, permitiendo establecer sistemas de referencia de coordenadas mediante códigos EPSG o definiciones CRS personalizadas, establecer conversiones de mapa con coordenadas este/norte y configurar el posicionamiento geográfico del sitio. Ejemplo: "Georreferencia este modelo IFC usando EPSG:4326 con coordenadas en latitud 40.7589, longitud -73.9851"

export_bc3_budget: Exporta un archivo de presupuesto BC3 (formato FIEBDC-3/2016) basado en el modelo IFC cargado en Blender. Esta herramienta crea un presupuesto de construcción completo extrayendo la estructura espacial IFC, agrupando los elementos de construcción por tipo y categoría (estructura, albañilería, forjados, carpintería, instalaciones, mobiliario), asignando precios unitarios de una base de datos integral y generando mediciones detalladas. Admite salida multilingüe (español/inglés) con codificación adecuada para caracteres internacionales. El formato BC3 es el estándar español para presupuestos de construcción y estimación de costes. Ejemplo: "Genera un archivo de presupuesto BC3 en español para este modelo de edificio"

Características

  • Categorización automática de elementos: Los elementos de construcción se clasifican automáticamente en categorías:

    • ESTR: Elementos estructurales (vigas, columnas, zapatas, pilotes, rampas, escaleras)
    • ALB: Albañilería (muros)
    • FORG: Forjados y cubiertas
    • CARP: Carpintería (puertas, ventanas)
    • INST: Instalaciones (tuberías, accesorios, terminales, barandillas)
    • MOB: Mobiliario

  • Mediciones precisas:

    • Muros medidos por NetSideArea (considera aberturas como puertas y ventanas)
    • Forjados y cubiertas medidos por GrossVolume
    • Vigas, columnas y pilotes medidos por longitud (metros)
    • Puertas, ventanas y mobiliario contados como unidades

  • Soporte multilingüe: Genera presupuestos en español o inglés con codificación de caracteres adecuada (windows-1252)

  • Estructura jerárquica: Los capítulos del presupuesto siguen la jerarquía espacial IFC (Proyecto → Sitio → Edificio → Planta)

  • Base de datos de precios unitarios: Incluye precios unitarios integrales para elementos de construcción comunes, totalmente personalizables mediante archivos JSON

  • Mediciones ordenadas: Los elementos dentro de cada categoría se ordenan alfabéticamente para facilitar su revisión

Archivos de Configuración

La exportación BC3 utiliza archivos de configuración JSON externos ubicados en resources/bc3_helper_files/:

  • precios_unitarios.json / unit_prices.json: Precios unitarios por tipo de elemento IFC
  • spatial_labels_es.json / spatial_labels_en.json: Traducciones de elementos espaciales
  • element_categories.json: Mapeos de tipo IFC a categoría de presupuesto

Estos archivos se pueden personalizar para adaptar la generación de presupuestos a necesidades específicas del proyecto o estándares de precios regionales.

Salida

Los archivos BC3 se exportan a la carpeta exports/ con el formato FIEBDC-3/2016 adecuado, incluidos:

  • Estructura jerárquica completa de capítulos
  • Mediciones detalladas para cada elemento
  • Precios unitarios y totales
  • Cumplimiento total con el estándar español de presupuestos de construcción bc3

Recursos MCP

Esta integración proporciona acceso a documentación estructurada mediante recursos MCP:

file://table_of_contents.md: Contiene la plantilla completa de estructura de informe técnico para generar informes integrales de edificios. Este recurso proporciona un índice estandarizado que puede utilizarse como referencia al crear documentación técnica a partir de modelos IFC.

Prompts MCP

El servidor incluye Prompts MCP especializados para la generación automatizada de informes:

Technical_building_report: Genera informes técnicos integrales de edificios basados en modelos IFC cargados en Blender. Este prompt proporciona un flujo de trabajo estructurado para crear documentación arquitectónica profesional en múltiples idiomas (inglés, español, francés, alemán, italiano, portugués). El prompt guía el análisis mediante la extracción sistemática de datos del modelo IFC, incluidos estructura espacial, cantidades, materiales y sistemas de construcción, culminando en un informe técnico completo con dibujos y visualizaciones 3D.

Ejecutar Código de Blender

Funcionalidad heredada de la implementación MCP original. Permite a Claude ejecutar código Python arbitrario en Blender. Úsalo con precaución.

Herramienta de Pensamiento Secuencial

Esta integración incluye la herramienta de Pensamiento Secuencial para la resolución estructurada de problemas y el análisis. Facilita un proceso de pensamiento paso a paso que puede ramificarse, revisarse y adaptarse a medida que se profundiza la comprensión, perfecto para el análisis complejo de modelos IFC o tareas de planificación.

Ejemplo: "Usa pensamiento secuencial para analizar la eficiencia energética de este edificio basándote en el modelo IFC"

Comandos de Ejemplo

Aquí hay algunos ejemplos de lo que puedes pedirle a Claude que haga con modelos IFC:

  • "Analiza este modelo IFC y dime cuántos muros, puertas y ventanas tiene"

  • "Muéstrame la estructura espacial de este modelo de edificio"

  • "Lista todos los espacios de este modelo IFC y sus propiedades"

  • "Identifica todos los elementos estructurales de este edificio"

  • "¿Cuáles son las relaciones entre este muro y otros elementos?"

  • "Genera un informe de las mediciones del modelo IFC abierto en Blender"

  • "Usa pensamiento secuencial para crear un plan de mantenimiento para este edificio basándote en el modelo IFC"

  • "Genera un archivo de presupuesto BC3 en español para el modelo IFC actual"

  • "Exporta una estimación de costes de construcción al formato BC3 con descripciones en inglés"

Solución de Problemas

  • Problemas de conexión: Asegúrate de que el servidor del addon de Blender esté ejecutándose y que el servidor MCP esté configurado en Claude
  • El modelo IFC no carga: Verifica que tengas el addon Bonsai BIM instalado y que un archivo IFC esté cargado
  • Errores de tiempo de espera: Intenta simplificar tus solicitudes o dividirlas en pasos más pequeños

Docker:

  • Errores de "conexión rechazada": Asegúrate de que Blender esté ejecutándose y que el addon esté habilitado con el servidor iniciado
  • Problemas de CORS: La API tiene CORS habilitado por defecto para todos los orígenes. Si encuentras problemas, verifica la configuración de CORS de tu cliente
  • Preocupaciones de rendimiento: Para modelos IFC grandes, las respuestas de la API podrían ser más lentas. Considera ajustar los tiempos de espera en tu cliente

Detalles Técnicos

La integración de IFC utiliza el módulo Bonsai BIM para acceder a la funcionalidad de ifcopenshell dentro de Blender. La comunicación sigue el mismo protocolo basado en JSON sobre sockets TCP que el BlenderMCP original.

Limitaciones y Consideraciones de Seguridad

  • La herramienta execute_blender_code del proyecto original sigue disponible, permitiendo ejecutar código Python arbitrario en Blender. Úsala con precaución y guarda siempre tu trabajo.

  • Los modelos IFC complejos pueden requerir dividir las operaciones en pasos más pequeños.

  • El rendimiento de las consultas IFC depende del tamaño y la complejidad del modelo.

  • La herramienta Get User View devuelve una imagen codificada en base64. Asegúrate de que el cliente la soporte.

Contribuciones

Este repositorio con licencia MIT está abierto para ser bifurcado, modificado y utilizado de cualquier manera. Estoy abierto a ideas y colaboraciones, así que no dudes en ponerte en contacto conmigo para contribuciones.

Créditos

PENDIENTE

Integración y pruebas con más clientes MCP