Bonsai-mcp - Model Context Protocol Integration for IFC through IfcOpenShell and Blender
Bonsai-mcp is a fork of BlenderMCP that extends the original functionality with dedicated support for IFC (Industry Foundation Classes) models through Bonsai. This integration is a platform to let LLMs read and modify IFC files.
Features
-
IFC-specific functionality: Query IFC models, analyze spatial structures, examine building elements and extract quantities
-
Eleven IFC tools included: Inspect project info, list entities, examine properties, explore spatial structure, analyze relationships and more
-
Sequential Thinking: Includes the sequential thinking tool from modelcontextprotocol/servers for structured problem solving
-
Execute Code tool from the original BlenderMCP implementation: Create and modify objects, apply materials, and execute Python code in Blender
Components
The system consists of two main components:
-
Blender Addon (
addon.py): A Blender addon that creates a socket server within Blender to receive and execute commands, including IFC-specific operations -
MCP Server (
tools.py): A Python server that implements the Model Context Protocol and connects to the Blender addon
Installation - Through MCP Client Settings
Prerequisites
-
Blender 4.0 or newer
-
Python 3.12 or newer
-
uv package manager
-
Bonsai BIM addon for Blender (for IFC functionality)
Installing uv:
Mac:
brew install uv
Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
set Path=C:\Users\[username]\.local\bin;%Path%
For other platforms, see the uv installation guide.
Clone the repository
git clone https://github.com/JotaDeRodriguez/Bonsai_mcp
Claude for Desktop Integration
Edit your claude_desktop_config.json file (Claude > Settings > Developer > Edit Config) to include:
{
"mcpServers": {
"Bonsai-mcp": {
"command": "uv",
"args": [
"--directory",
"\\your\\path\\to\\Bonsai_mcp",
"run",
"tools.py"
]
}
}
}
Installation via Docker
The repository comes with a Dockerfile that makes deployment simple and consistent across different environments.
Quick Start
# 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
Once running, the container will expose the MCP tools as REST/OpenAPI APIs at http://localhost:8000.
- To verify youtr installation, open your browser and navigate to
http://localhost:8000/docs- You'll see the Swagger UI with all available endpoints
- Test an endpoint by clicking on it, then click "Try it out" and "Execute"
Connecting to Open WebUI or Other API Clients
To connect this API to Open WebUI:
- In Open WebUI, go to Settings > Manage Tool Servers
- Add a new connection with:
- URL:
http://localhost:8000 - Path to OpenAPI spec:
/openapi.json - Authentication: None (unless configured otherwise)
Environment Variables
The Docker container accepts several environment variables to customize its behavior:
# 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
Installing the Blender Addon
-
Download the
addon.pyfile from this repo -
Open Blender
-
Go to Edit > Preferences > Add-ons
-
Click "Install..." and select the
addon.pyfile -
Enable the addon by checking the box next to "Interface: Blender MCP - IFC"
Usage
Starting the Connection
-
In Blender, go to the 3D View sidebar (press N if not visible)
-
Find the "Blender MCP - IFC" tab
-
Click "Connect to Claude"
-
Make sure the MCP server is running
Using with Claude
Once connected, you'll see a hammer icon in Claude's interface with tools for the Blender MCP IFC integration.
IFC Tools
This repo includes multiple IFC-specific tools that enable comprehensive querying and manipulation of IFC models:
get_ifc_project_info: Retrieves basic information about the IFC project, including name, description, and counts of different entity types. Example: "What is the basic information about this IFC project?"
list_ifc_entities: Lists IFC entities of a specific type (walls, doors, spaces, etc.) with options to limit results and filter by selection. Example: "List all the walls in this IFC model" or "Show me the windows in this building"
get_ifc_properties: Retrieves all properties of a specific IFC entity by its GlobalId or from currently selected objects. Example: "What are the properties of this wall with ID 1Dvrgv7Tf5IfTEapMkwDQY?"
get_ifc_spatial_structure: Gets the spatial hierarchy of the IFC model (site, building, storeys, spaces). Example: "Show me the spatial structure of this building"
get_ifc_relationships: Retrieves all relationships for a specific IFC entity. Example: "What are the relationships of the entrance door?"
get_selected_ifc_entities: Gets information about IFC entities corresponding to objects currently selected in the Blender UI. Example: "Tell me about the elements I've selected in Blender"
get_user_view: Captures the current Blender viewport as an image, allowing visualization of the model from the user's perspective. Example: "Show me what the user is currently seeing in Blender"
export_ifc_data: Exports IFC data to a structured JSON or CSV file, with options to filter by entity type or building level. Example: "Export all wall data to a CSV file"
place_ifc_object: Creates and positions an IFC element in the model at specified coordinates with optional rotation. Example: "Place a door at coordinates X:10, Y:5, Z:0 with 90 degrees rotation"
get_ifc_quantities: Calculate and get quantities (m2, m3, etc.) for IFC elements, with options to filter by entity type or selected ones. Example: "Give me the area of all the walls in the building using the tool get_ifc_quantities"
get_ifc_total_structure: Retrieves the complete hierarchical structure of the IFC model including spatial elements (Project, Site, Building, Storeys) and all building elements within each spatial container. This comprehensive view combines spatial hierarchy with building elements, essential for generating complete reports and budgets. Example: "Show me the complete structure of this IFC model including all building elements organized by floor"
export_drawing_png: Exports 2D and 3D drawings as high-resolution PNG images with customizable resolution and view parameters. Creates orthographic plan views from above at specified height offsets. Example: "Generate a floor plan PNG for the ground floor at 1920x1080 resolution"
get_ifc_georeferencing_info: Retrieves comprehensive georeferencing information from IFC files including coordinate reference systems (CRS), map conversions, world coordinate systems, true north direction, and site geographic coordinates. Example: "What georeferencing information is available in this IFC model?"
georeference_ifc_model: Creates or updates georeferencing information in IFC models, allowing you to set coordinate reference systems using EPSG codes or custom CRS definitions, establish map conversions with eastings/northings coordinates, and configure site geographic positioning. Example: "Georeference this IFC model using EPSG:4326 with coordinates at latitude 40.7589, longitude -73.9851"
export_bc3_budget: Exports a BC3 budget file (FIEBDC-3/2016 format) based on the IFC model loaded in Blender. This tool creates a complete construction budget by extracting the IFC spatial structure, grouping building elements by type and category (structure, masonry, slabs, carpentry, installations, furniture), assigning unit prices from a comprehensive database, and generating detailed measurements. Supports multi-language output (Spanish/English) with proper encoding for international characters. The BC3 format is the Spanish standard for construction budgets and cost estimation. Example: "Generate a BC3 budget file in Spanish for this building model"
Features
-
Automatic element categorization: Building elements are automatically classified into categories:
- ESTR: Structural elements (beams, columns, footings, piles, ramps, stairs)
- ALB: Masonry (walls)
- FORG: Slabs and roofs
- CARP: Carpentry (doors, windows)
- INST: Installations (pipes, fittings, terminals, railings)
- MOB: Furniture
-
Accurate measurements:
- Walls measured by NetSideArea (accounts for openings like doors and windows)
- Slabs and roofs measured by GrossVolume
- Beams, columns, and piles measured by length (meters)
- Doors, windows, and furniture counted as units
-
Multi-language support: Generate budgets in Spanish or English with proper character encoding (windows-1252)
-
Hierarchical structure: Budget chapters follow the IFC spatial hierarchy (Project → Site → Building → Storey)
-
Unit price database: Includes comprehensive unit prices for common construction elements, fully customizable via JSON files
-
Sorted measurements: Elements within each category are sorted alphabetically for easier review
Configuration Files
The BC3 export uses external JSON configuration files located in resources/bc3_helper_files/:
precios_unitarios.json/unit_prices.json: Unit prices per IFC element typespatial_labels_es.json/spatial_labels_en.json: Spatial element translationselement_categories.json: IFC type to budget category mappings
These files can be customized to adapt the budget generation to specific project needs or regional pricing standards.
Output
BC3 files are exported to the exports/ folder with proper FIEBDC-3/2016 format, including:
- Complete hierarchical chapter structure
- Detailed measurements for each element
- Unit prices and totals
- Full compliance with Spanish construction budget standard bc3
MCP Resources
This integration provides access to structured documentation through MCP resources:
file://table_of_contents.md: Contains the complete technical report structure template for generating comprehensive building reports. This resource provides a standardized table of contents that can be used as a reference when creating technical documentation from IFC models.
MCP Prompts
The server includes specialized MCP Prompts for automated report generation:
Technical_building_report: Generates comprehensive technical building reports based on IFC models loaded in Blender. This prompt provides a structured workflow for creating professional architectural documentation in multiple languages (English, Spanish, French, German, Italian, Portuguese). The prompt guides the analysis through systematic data extraction from the IFC model, including spatial structure, quantities, materials, and building systems, culminating in a complete technical report with drawings and 3D visualizations.
Execute Blender Code
Legacy feature from the original MCP implementation. Allows Claude to execute arbitrary Python code in Blender. Use with caution.
Sequential Thinking Tool
This integration includes the Sequential Thinking tool for structured problem-solving and analysis. It facilitates a step-by-step thinking process that can branch, revise, and adapt as understanding deepens - perfect for complex IFC model analysis or planning tasks.
Example: "Use sequential thinking to analyze this building's energy efficiency based on the IFC model"
Example Commands
Here are some examples of what you can ask Claude to do with IFC models:
-
"Analyze this IFC model and tell me how many walls, doors and windows it has"
-
"Show me the spatial structure of this building model"
-
"List all spaces in this IFC model and their properties"
-
"Identify all structural elements in this building"
-
"What are the relationships between this wall and other elements?"
-
"Generate a report of the measurements from the IFC model opened in Blender"
-
"Use sequential thinking to create a maintenance plan for this building based on the IFC model"
-
"Generate a BC3 budget file in Spanish for the current IFC model"
-
"Export a construction cost estimate to BC3 format with English descriptions"
Troubleshooting
- Connection issues: Make sure the Blender addon server is running, and the MCP server is configured in Claude
- IFC model not loading: Verify that you have the Bonsai BIM addon installed and that an IFC file is loaded
- Timeout errors: Try simplifying your requests or breaking them into smaller steps
Docker:
- "Connection refused" errors: Make sure Blender is running and the addon is enabled with the server started
- CORS issues: The API has CORS enabled by default for all origins. If you encounter issues, check your client's CORS settings
- Performance concerns: For large IFC models, the API responses might be slower. Consider adjusting timeouts in your client
Technical Details
The IFC integration uses the Bonsai BIM module to access ifcopenshell functionality within Blender. The communication follows the same JSON-based protocol over TCP sockets as the original BlenderMCP.
Limitations & Security Considerations
-
The
execute_blender_codetool from the original project is still available, allowing running arbitrary Python code in Blender. Use with caution and always save your work. -
Complex IFC models may require breaking down operations into smaller steps.
-
IFC query performance depends on model size and complexity.
-
Get User View tool returns a base64 encoded image. Please ensure the client supports it.
Contributions
This MIT licensed repo is open to be forked, modified and used in any way. I'm open to ideas and collaborations, so don't hesitate to get in contact with me for contributions.
Credits
-
Original BlenderMCP by Siddharth Ahuja
-
Sequential Thinking tool from modelcontextprotocol/servers
-
IFC integration built upon the Bonsai BIM addon for Blender
TO DO
Integration and testing with more MCP Clients