Bonsai BIM (Blender IFC) MCP server for AI agents

Bonsai-mcp is a specialized integration of the Model Context Protocol (MCP) that allows large language models to interact with IFC (Industry Foundation Classes) models through IfcOpenShell and Blender. This powerful tool enables you to query, analyze, and modify IFC files using natural language through Claude or other compatible AI assistants.

Installation Options

Prerequisites

Blender 4.0 or newer
Python 3.12 or newer
uv package manager
Bonsai BIM addon for Blender (for IFC functionality)

Installing uv Package Manager

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.

Method 1: Claude for Desktop Integration

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"
          ]
        }
    }
}

Method 2: Docker Installation

# 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 your installation, navigate to http://localhost:8000/docs in your browser to see the Swagger UI with all available endpoints.

Docker Environment Variables

# 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

Connecting 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)

Installing the Blender Addon

Download the addon.py file from the repository
Open Blender
Go to Edit > Preferences > Add-ons
Click "Install..." and select the addon.py file
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

IFC Tools Available

get_ifc_project_info: Retrieves basic information about the IFC project
list_ifc_entities: Lists IFC entities of a specific type (walls, doors, spaces, etc.)
get_ifc_properties: Retrieves all properties of a specific IFC entity
get_ifc_spatial_structure: Gets the spatial hierarchy of the IFC model
get_ifc_relationships: Retrieves all relationships for a specific IFC entity
get_selected_ifc_entities: Gets information about currently selected IFC entities
get_user_view: Captures the current Blender viewport as an image
export_ifc_data: Exports IFC data to a structured JSON or CSV file
place_ifc_object: Creates and positions an IFC element at specified coordinates

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?"

Sequential Thinking Tool

This integration includes a Sequential Thinking tool for structured problem-solving and analysis. It facilitates a step-by-step thinking process for complex IFC model analysis or planning tasks.

Example: "Use sequential thinking to analyze this building's energy efficiency based on the IFC model"

Troubleshooting

Connection issues: Make sure the Blender addon server is running, and the MCP server is configured correctly
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-specific Issues

"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. Check your client's CORS settings
Performance concerns: For large IFC models, the API responses might be slower. Consider adjusting timeouts in your client

How to add this MCP server to Cursor

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.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

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.

How to use the MCP server

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.