Bonsai MCP Server

How to use

Connect your MCP client to the Bonsai MCP server to start issuing commands that operate on IFC models loaded in Blender. Once connected, you can query project information, inspect spatial structures, examine properties of IFC elements, and perform actions like placing or editing objects, exporting data, or generating budgets. Use sequential thinking prompts to plan multi-step analyses or build reports that combine IFC data with visuals from Blender.

How to install

Prerequisites you need before installing Bonsai MCP:

- Blender 4.0 or newer

- Python 3.12 or newer

- uv package manager

- Bonsai BIM addon for Blender (for IFC functionality)

Step-by-step setup for a local stdio MCP server

{
  "type": "stdio",
  "name": "bonsai_mcp",
  "command": "uv",
  "args": [
    "--directory",
    "\\your\\path\\to\\Bonsai_mcp",
    "run",
    "tools.py"
  ],
  "env": []
}

Optional Docker deployment

Build and run the container to expose MCP tools via REST/OpenAPI at http://localhost:8000.

# 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

Connecting to Open WebUI or other API clients

Use the exposed API at http://localhost:8000. Open API docs are available at http://localhost:8000/docs which provides an interactive Swagger UI to test endpoints.

Blender addon setup

1) In Blender, download addon.py and place it where you can access it.

2) In Blender, go to Edit > Preferences > Add-ons, then Install… and select addon.py.

3) Enable the addon by checking the option labeled “Interface: Blender MCP - IFC”.

Claude for Desktop integration

Configure Claude to connect to Bonsai MCP by editing your Claude desktop config to include the MCP server entry that launches uv with the Bonsai MCP script.

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

IFC tools you can use

The Bonsai MCP suite includes a set of IFC-specific tools to read and modify IFC data within Blender.

Examples of available tools include functions to retrieve project info, list IFC entities, fetch properties, explore spatial structures, inspect relationships, export IFC data, place IFC objects, compute quantities, and export budgets in BC3 format.

Starting and using the connection

1) Ensure the MCP server is running (the stdio server started with uv as shown above).

2) In Blender, open the 3D View sidebar and select the Blender MCP - IFC tab.

3) Click Connect to Claude to establish the link and begin issuing IFC commands.

Example workflows

- Analyze an IFC model to count walls, doors, and windows, then generate a spatial report showing the building’s hierarchy.

- Retrieve and export all wall properties, then place a new window element at a specific location.

- Create a BC3 budget from the IFC model, organized by spatial chapters (Project → Site → Building → Storey).

Troubleshooting

Connection issues: ensure the Blender addon is running and the MCP server is correctly configured in Claude.

IFC model not loading: verify the Bonsai BIM addon is installed and an IFC file is loaded.

Timeouts: break requests into smaller steps or simplify queries to improve responsiveness.

Notes on security and usage

The option to execute Blender Python code remains available but should be used with caution. Save work frequently when running code snippets.

Technical context

This integration leverages the Bonsai BIM addon to access ifcopenshell functionality within Blender and communicates over a JSON-based protocol via TCP sockets, enabling seamless MCP client interactions.

Credits and provenance

The integration builds on the original BlenderMCP for Blender, with enhancements to support IFC workflows via Bonsai.

get_ifc_project_info

Retrieves basic information about the IFC project including name, description, and entity counts.

list_ifc_entities

Lists IFC entities of a specific type (e.g., walls, doors) with optional limits and filters.

get_ifc_properties

Retrieves all properties of a specific IFC entity by GlobalId or from currently selected objects.

get_ifc_spatial_structure

Obtains the spatial hierarchy of the IFC model (Site, Building, Storey, Space).

get_ifc_relationships

Retrieves relationships for a specific IFC entity.

get_selected_ifc_entities

Returns information about IFC entities corresponding to objects currently selected in Blender.

get_user_view

Captures the current Blender viewport as an image for visualization.

export_ifc_data

Exports IFC data to JSON or CSV with optional filtering by type or level.

place_ifc_object

Creates and positions an IFC element at specified coordinates with optional rotation.

get_ifc_quantities

Calculates quantities (area, volume, length, units) for IFC elements with filters.

get_ifc_total_structure

Retrieves the complete hierarchical structure including spatial containers and building elements.

export_drawing_png

Exports 2D/3D drawings as high-resolution PNGs with configurable view parameters.

get_ifc_georeferencing_info

Retrieves georeferencing information such as CRS and site coordinates.

georeference_ifc_model

Applies or updates georeferencing data using CRS codes and map conversions.

export_bc3_budget

Exports a BC3 budget file from the IFC model, with multi-language support and unit price integration.