Bonsai-mcp is a powerful Model Context Protocol integration that enables Large Language Models (LLMs) to interact with IFC (Industry Foundation Classes) files through Blender. This tool allows for querying IFC models, analyzing spatial structures, examining building elements, and extracting quantities using eleven specialized IFC tools.
brew install uv
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.
First, clone the repository:
git clone https://github.com/JotaDeRodriguez/Bonsai_mcp
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"
]
}
}
}
# 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
Verify the installation by accessing http://localhost:8000/docs in your browser, where you'll see the Swagger UI with all available endpoints.
# 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
addon.py file from the repositoryaddon.py fileOnce connected, you'll see a hammer icon in Claude's interface with tools for the Blender MCP IFC integration.
Bonsai-mcp includes multiple specialized IFC tools:
Retrieves basic information about the IFC project, including name, description, and entity counts.
Example: "What is the basic information about this IFC project?"
Lists IFC entities of a specific type with filtering options.
Example: "List all the walls in this IFC model"
Retrieves properties of a specific IFC entity by GlobalId or from selected objects.
Example: "What are the properties of this wall with ID 1Dvrgv7Tf5IfTEapMkwDQY?"
Shows the spatial hierarchy of the IFC model (site, building, storeys, spaces).
Example: "Show me the spatial structure of this building"
Gets all relationships for a specific IFC entity.
Example: "What are the relationships of the entrance door?"
Retrieves information about IFC entities currently selected in Blender.
Example: "Tell me about the elements I've selected in Blender"
Captures the current Blender viewport as an image.
Example: "Show me what the user is currently seeing in Blender"
Exports IFC data to JSON or CSV, with filtering options.
Example: "Export all wall data to a CSV file"
Creates and positions IFC elements at specified coordinates.
Example: "Place a door at coordinates X:10, Y:5, Z:0 with 90 degrees rotation"
Calculates quantities for IFC elements.
Example: "Give me the area of all the walls in the building"
Gets the complete hierarchical structure of the IFC model.
Example: "Show me the complete structure of this IFC model including all building elements organized by floor"
Exports 2D/3D drawings as PNG images.
Example: "Generate a floor plan PNG for the ground floor at 1920x1080 resolution"
Retrieves georeferencing information from IFC files.
Example: "What georeferencing information is available in this IFC model?"
Creates or updates georeferencing information in IFC models.
Example: "Georeference this IFC model using EPSG:4326 with coordinates at latitude 40.7589, longitude -73.9851"
Exports a BC3 budget file based on the IFC model.
Example: "Generate a BC3 budget file in Spanish for this building model"
Facilitates structured problem-solving through step-by-step analysis.
Example: "Use sequential thinking to analyze this building's energy efficiency based on the IFC model"
Executes Python code in Blender (use with caution).
To add this MCP server to Claude Code, run this command in your terminal:
claude mcp add-json "Bonsai-mcp" '{"command":"uv","args":["--directory","\\your\\path\\to\\Bonsai_mcp","run","tools.py"]}'See the official Claude Code MCP documentation for more details.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.
To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".
When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:
{
"mcpServers": {
"Bonsai-mcp": {
"command": "uv",
"args": [
"--directory",
"\\your\\path\\to\\Bonsai_mcp",
"run",
"tools.py"
]
}
}
}To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json2. Add this to your configuration file:
{
"mcpServers": {
"Bonsai-mcp": {
"command": "uv",
"args": [
"--directory",
"\\your\\path\\to\\Bonsai_mcp",
"run",
"tools.py"
]
}
}
}3. Restart Claude Desktop for the changes to take effect