IFC Bonsai MCP

IFC-Bonsai-MCP is an MCP server that connects AI language models with the Bonsai Blender add-on to read, create, and edit IFC models directly via high-level tool calls.

This repository is associated with the paper: MCP4IFC: IFC-Based Building Design using Large Language Models | Project Page · arXiv · Experiment Results

🚀 Highlights:

• AI-Driven BIM: Use natural language to create and edit IFC elements like walls, doors, roofs, and stairs directly within Blender.
• RAG-Powered Knowledge: Leverage a Retrieval-Augmented Generation system with a local vector index for instant, semantic search across IFC and IfcOpenShell documentation.
• Advanced Geometry Generation: Create complex 3D geometry using Python and Trimesh, with tools to convert procedural meshes into native IFC elements.
• Extensible Toolset: A comprehensive set of over 50 MCP tools for scene analysis, object manipulation, parametric creation, and knowledge retrieval.

Installation Guide

Prerequisites

• Blender 4.4+ with Bonsai Add-on 0.8.2+
• Python 3.10+ (ensure it's in your PATH)
• UV Package Manager: pip install uv
• Claude Desktop or any MCP-compatible client

Quick Installation

This is a quick overview of installation steps in the global Python environment. For more details or virtual environment setup, check the section below.

# 1. Clone and setup
git clone [REPOSITORY_URL] && cd [REPOSITORY_NAME]

# 2. Install dependencies
pip install uv
uv sync

# 3. Install Blender packages (automatic)
python scripts/install_blender_packages.py

# 4. Create the zip file of blender_addon folder manually or use the helper script:
python scripts/install.py --create-addon-zip
# Then: Blender → Edit → Preferences → Add-ons → Install → blender_addon.zip
# After installing the add-on: Go to Blender UI → Sidebar Add-On Panel → BlenderMCP → Click "Connect to MCP server"

# 5. Configure Claude Desktop (Edit Config in Settings → Developer)
# Add: 
# {
#   "mcpServers": {
#     "blender": {
#       "command": "python",
#       "args": ["-m", "blender_mcp.server"],
#     }
#   }
# }

# 6. (Optional) Setup knowledge base
uv run python scripts/init_knowledge_base.py
uv run python scripts/embedding_server.py --model sentence-transformers/all-MiniLM-L6-v2 --host 127.0.0.1 --port 8080 --normalize

Here is the workflow diagram in Claude Desktop for reference:

If there are any issues, please refer to the detailed installation steps below.

Step-by-Step Installation

• Step 1: Clone and navigate to the project

  git clone [REPOSITORY_URL]
  cd [REPOSITORY_NAME]
  

• Step 2: Create and set up the virtual environment. This is for the MCP server that will run in the system/virtual environment.

  uv sync
  # Creates virtual environment: If `.venv/` doesn't exist, it creates one and installs all dependencies
  # Uses lock file: Ensures exact same versions as specified in `uv.lock`
  # Check https://docs.astral.sh/uv/ for using custom venv paths or names.
  

  Activate the virtual environment:

  source .venv/bin/activate    # Linux/macOS
  .venv\Scripts\activate       # Windows
  

  (Alternative) For a global installation, install all dependencies in your system Python environment:

  uv pip install . # records the install in uv.lock
  pip install .    # or, with pip
  

• Step 3: Install Blender-specific packages (Required).

... View full README on GitHub