Show2Instruct/ifc-bonsai-mcp

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). These are required for the Blender add-on to function correctly.

  The MCP server runs in your system's Python environment, but the Blender add-on runs inside Blender's Python environment. Some packages need to be installed specifically in Blender:

  • Option A: Automatic Installation (Recommended) using the helper script:

    python scripts/install_blender_packages.py
    

    This script automatically finds your Blender installation(s), installs all required packages (ifcopenshell, trimesh, pillow, numpy), and tests that everything works correctly

  • Option B: Manual Installation

    # Navigate to Blender's Python directory (adjust path for your Blender installation)
    # Windows (typical path):
    cd "C:\Program Files\Blender Foundation\Blender 4.4\4.4\python\bin"
    
    # Install required packages for Blender add-on
    python.exe -m pip install ifcopenshell>=0.7.0
    python.exe -m pip install trimesh>=3.24.0  
    python.exe -m pip install pillow>=10.0.0
    python.exe -m pip install numpy>=1.26.0
    

  • Option C: Using Blender's Console

    # 1. Open Blender
    # 2. Go to Scripting workspace
    # 3. Run this in the Python console:
    import subprocess
    import sys
    subprocess.check_call([sys.executable, "-m", "pip", "install", "ifcopenshell>=0.7.0", "trimesh>=3.24.0", "pillow>=10.0.0", "numpy>=1.26.0"])
    

Blender Add-on Packaging

The Blender add-on enables communication between Blender and the MCP server. To install it:

1. Create a zip file of the blender_addon folder
   • Either manually or run python scripts/install.py --create-addon-zip
2. In Blender, go to Edit > Preferences > Add-ons > Install...
3. Select the blender_addon.zip file and activate the add-on
4. In the main Blender UI, open Sidebar Add-On Panel → BlenderMCP → Connect to MCP server. Check /figs/workflow.png for reference.

Configuring Claude Desktop

For Virtual Environment Installation

If you installed using a virtual environment, you need to point Claude to the Python executable in the virtual environment:

1. Open Claude Desktop > Settings > Developer > Edit Config File.
2. Add this configuration:

   {
     "mcpServers": {
       "blender": {
         "command": "C:\\path\\to\\ifc-bonsai-mcp\\.venv\\Scripts\\python.exe",
         "args": ["-m", "blender_mcp.server"],
       }
     }
   }
   

   Note: On Windows, use double backslashes (\\) in file paths. On macOS and Linux, use forward slashes (/).

For Global Installation

If you installed globally, use the system Python:

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["-m", "blender_mcp.server"],
    }
  }
}

3. Important: Replace C:/path/to/ifc-bonsai-mcp with your actual project path
4. Restart Claude Desktop

Running the MCP Server

Important: Since the project tries to save to an IFC file and loads it, always create an empty file and save it before doing any operations. Because the MCP server directly loads the IFC file and does the edits. If a new project is created and no .ifc file is saved, then the MCP server will not update in the actual blender scene. Just do ctrl (cmd) + S and save an empty IFC file if a new project is created.

If there are connection issues please check if the "Connect to MCP server" button in the Blender add-on panel has been clicked. Check the /figs/workflow.png to see where it is located.

Code Execution Limitations: The general execute_code tool behaves unpredictably with IFC operations. The general execute code tool lacks proper context handling, cannot save changes back to the model consistently and may produce unsafe results for IFC operations. Consider disabling the general execute_code tool if there are issues.

Knowledge Base & Embeddings

The MCP server includes a RAG-powered tool to query IFC documentation and best practices. This uses a local ChromaDB index and an embedding model (Sentence Transformers). To use the RAG-powered IFC knowledge base, follow these steps:

• Initialize the Local Chroma Index

  uv run python scripts/init_knowledge_base.py
  

  This downloads the embedding model (Sentence Transformers) and caches the IFC knowledge base under .cache/chromadb/.

• Run the embedding model so the MCP server can use it for embedding generation:

  uv run python scripts/embedding_server.py --model sentence-transformers/all-MiniLM-L6-v2 --host 127.0.0.1 --port 8080 --normalize
  

  This starts a local embedding server that the MCP server can use for embedding generation. Adjust the model and port as needed. If the port is changed, the BLENDER_MCP_REMOTE_EMBEDDINGS_URL environment variable must be set accordingly.

List of Available Tools

The MCP server has various tools that can be called by the AI assistant. All available tools and their parameters are documented in the .

Contributing

Pull requests are welcome! See for the development workflow and for any issues.

Acknowledgements

This is not an official Blender, Bonsai or IfcOpenShell project. Thanks to BlenderMCP and Bonsai_mcp for their open source work.

Citation

Please consider citing our work if you find it useful or used in your research.

@misc{nithyanantham2025mcp4ifcifcbasedbuildingdesign,
      title={MCP4IFC: IFC-Based Building Design Using Large Language Models}, 
      author={Bharathi Kannan Nithyanantham and Tobias Sesterhenn and Ashwin Nedungadi and Sergio Peral Garijo and Janis Zenkner and Christian Bartelt and Stefan Lüdtke},
      year={2025},
      eprint={2511.05533},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2511.05533}, 
}