Bonsai MCP

A local Model Context Protocol server that connects any MCP client (Claude Desktop, Claude Code, Cursor, VS Code, OpenAI Codex) to a running Blender + Bonsai (BlenderBIM) session. Inspect the scene, query the loaded IFC project, capture the viewport, and run Python inside Blender.

MCP client  --stdio-->  bonsai-mcp  --127.0.0.1:9878-->  Blender add-on (bpy + Bonsai + IfcOpenShell)

This project is part of IFC-CoPilot: A Tool-Based Framework for LLM-Driven IFC Building Design.

This repository is an updated and simpler version of ifc-bonsai-mcp. We used the original repository for the experiments in the MCP4IFC paper. The original repository is still available. It contains many predefined tools. This repository mainly uses code generation. Modern LLMs are very good at generating IfcOpenShell code. Code generation can therefore handle many IFC tasks. It is also more flexible than using many fixed tools. We have improved and simplified the code-generation workflow in this MCP server. The server is lightweight, easy to connect, and easy to use. We recommend this repository for most users. We will also keep it updated and continue improving it.

Requirements

• Blender 3.6+ (4.x recommended).
• Bonsai (BlenderBIM), only for the IFC tools. Install it from bonsaibim.org.
• uv, one-time install below. Runs the server and handles Python 3.10+ for you.
• git, to clone this repo. The server runs from your local checkout; it is not published to PyPI.

Setup (one-time)

Do these once. uv installs everything into the repo's own .venv the first time you run it; nothing is installed globally, and nothing is fetched from PyPI.

1. Install uv:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone this repo somewhere permanent, and note its full path; you point your MCP client at it below:

git clone https://github.com/show2instruct/bonsai-mcp.git

Quick start

1. Install the Blender add-on

1. In Blender: Edit > Preferences > Add-ons. On Blender 4.2+/5.x, open the ▾ menu (top-right) > Install from Disk...; on older versions use the Install... button.
2. Pick blender_addon/bonsai_bridge.py from the repo you cloned: that exact file, not scripts/package_addon.py or the .zip. Then tick Bonsai MCP Bridge to enable it.
3. Open the sidebar (press N) > Bonsai MCP tab > Start Bridge. It now listens on 127.0.0.1:9878.

2. Connect your client

Point your client at the folder you cloned. Everywhere below, replace /path/to/bonsai-mcp with that path. On Windows in JSON, either use forward slashes or double every backslash (C:\\Users\\you\\bonsai-mcp).

• Claude Code:

  claude mcp add bonsai-mcp -- uv run --directory /path/to/bonsai-mcp bonsai-mcp

• Claude Desktop, Cursor, VS Code, and other clients: add this to the client's MCP config, then restart the client:

  {
    "mcpServers": {
      "bonsai-mcp": {
        "command": "uv",
        "args": ["run", "--directory", "/path/to/bonsai-mcp", "bonsai-mcp"]
      }
    }
  }

  On Windows, if the client can't find uv, use its full path as the command (e.g. C:\\Users\\you\\.local\\bin\\uv.exe).

uv run builds the project into the repo's .venv on first launch (editable, so your local edits take effect on the next restart) and caches it after that.

3. Verify

With Blender running and the bridge started, run this from inside the cloned folder:

uv run bonsai-mcp doctor

doctor pings the bridge and reports Blender / IfcOpenShell status and the tools it exposes.

Per-client config paths, the Windows uv.exe path note, and optional BONSAI_MCP_* settings are in docs/clients.md. Example configs live in examples/; set the --directory path to your clone.

Tools

Eleven tools, each tagged [QUERY] (read-only) or [EDIT] (mutates state).

Category	Tool	Purpose
QUERY	get_scene_info	Scene summary plus an optional filtered object list (paged).
QUERY	get_selected_objects	Per-object info for the current selection (capped).
QUERY	list_elements	IFC-backed elements filtered by class (inheritance-aware), name, or storey; paged.
QUERY	get_psets	IFC property and quantity sets for one or many objects (paged batches).
QUERY	get_viewport_screenshot	Capture the viewport: view or azimuth/elevation, direction-aware fit, per-storey floor plans, shading incl. color-by-class, plus structured viewport state with depth.
QUERY	get_ifc_project_info	Schema, counts, materials, classifications.
QUERY	get_spatial_structure	Site -> building -> storey -> space tree with element counts.
QUERY	get_quantities	Quantity takeoff (areas, volumes, lengths) by class, optionally per storey.
EDIT	execute_ifc_code	Run IfcOpenShell / Bonsai API code. bpy blocked.
EDIT	execute_blender_code	Run arbitrary Python with full bpy access.
EDIT	save_ifc_file	Save in place, save-as (guarded), and optional viewport reload.

Every tool returns structured content alongside readable JSON text, and the server also exposes MCP resources (bonsai://project, bonsai://scene, per-element psets) and two workflow prompts (model-audit, visual-verify).

Full reference with inputs, outputs, and examples: docs/tools.md.

Example prompt, with an IFC project open in Bonsai:

"List every wall in the model with its fire rating."

Safety

The bridge binds to 127.0.0.1 only and has no authentication, and execute_blender_code runs arbitrary Python. Treat it like an open Python REPL on your machine and never expose it to a network. See docs/safety.md.

Documentation

• Installation
• Client setup (Claude, Cursor, VS Code, OpenAI)
• Tools reference
• Safety
• Troubleshooting

Contributing

Python 3.10+ and uv:

uv venv
uv pip install -e ".[dev]"
uv run ruff check src tests blender_addon scripts
uv run pytest

Add tests and docs for behavior changes. Report security issues privately through GitHub Security Advisories.

License

MIT. See LICENSE.