bonsai-mcp

bonsai-mcp

MCP server to read, view and edit IFC models with IfcOpenShell and Bonsai (Blender).

Query a model, look at it through Blender's viewport, and edit it with IFCsemantics — profiles, placements, property sets — never raw mesh operations.The read tools run with Blender closed.

Status: Stage 3 — read tools, Blender/Bonsai viewport, and IFC-semantic editing.

Table of contents

• 1. Requirements
• 2. Install
• 3. Install the Blender add-on
• 4. Selfcheck
• 5. Claude Desktop config
• 6. Claude Code config
• 7. Usage procedure
• 8. Tool reference
• 9. Safe editing procedure
• 10. Unit conventions
• 11. Environment variables
• 12. Troubleshooting
• 13. Development

1. Requirements

The ifc_* tools run with Blender closed. The bl_* tools need Blender + Bonsai + the add-on.

2. Install

git clone https://github.com/nhantruong96/bonsai-mcp.git
cd bonsai-mcp
uv sync

To pin Python 3.13:

uv sync --python 3.13

Sample model. --selfcheck and pytest use KIT's FZK-Haus model. It is not committed — it is not this project's file — and is downloaded automatically on first run. Nothing to do.

Fetch it manually if the machine is offline at run time:

curl -L -o tests/fixtures/AC20-FZK-Haus.ifc https://www.ifcwiki.org/images/e/e3/AC20-FZK-Haus.ifc

Or point the selfcheck at any IFC file:

uv run python -m bonsai_mcp --selfcheck --file "D:\path\to\your.ifc"

3. Install the Blender add-on

Only needed for the bl_* tools. Skip this if you only use the read tools.

3.1. Install Bonsai (if it is not installed yet)

Blender 5.x runs Python 3.13 → take the bonsai_py313 build. Blender 4.2 runs Python 3.11 → bonsai_py311.

Blender → Edit > Preferences > Get Extensions → the ˅ button top right → Install from Disk... → pick the Bonsai zip.

3.2. Build the add-on zip

Compress-Archive -Path C:\Tools\bonsai-mcp\addon\bonsai_mcp_addon -DestinationPath C:\Tools\bonsai-mcp\bonsai_mcp_addon.zip -Force

3.3. Install the add-on

Blender → Edit > Preferences > Get Extensions → the ˅ button top right → Install from Disk... → pick bonsai_mcp_addon.zip.

3.4. Point the add-on at src

Edit > Preferences > Add-ons → Bonsai MCP Bridge → expand → fill in bonsai-mcp src:

C:\Tools\bonsai-mcp\src

This is what lets the ifc_* tools read the model Blender has open. Without it the bl_* tools still work but ifc_* cannot read through Blender.

Alternatively set the BONSAI_MCP_SRC environment variable, which takes precedence.

3.5. Run

1. Open an IFC file: Bonsai > Project > Load Project.
2. In the 3D viewport press N → Bonsai MCP tab → Start Server.
3. The panel shows Running, the address 127.0.0.1:9876, request/error counts and the last 20 log lines.

Change the port under Edit > Preferences > Add-ons > Bonsai MCP Bridge > Port, then set BONSAI_MCP_BLENDER_PORT to the same value on the MCP side.

4. Selfcheck

uv run python -m bonsai_mcp --selfcheck

uv run python -m bonsai_mcp --list-tools

uv run python -m pytest

Selfcheck exits 0 on success. All logging goes to stderr.

The Blender integration tests skip themselves when no bridge is running. To run them, Start Server in Blender then:

uv run python -m pytest tests/test_blender_integration.py -v

uv run python -m pytest tests/test_blender_edit_integration.py -v

5. Claude Desktop config

File: %APPDATA%\Claude\claude_desktop_config.json (Windows) ·~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "bonsai-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Tools\\bonsai-mcp",
        "run",
        "python",
        "-m",
        "bonsai_mcp"
      ],
      "env": {
        "BONSAI_MCP_BLENDER_HOST": "127.0.0.1",
        "BONSAI_MCP_BLENDER_PORT": "9876",
        "BONSAI_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

The env block is optional; leaving it out uses exactly those defaults.

Restart Claude Desktop after editing the file.

6. Claude Code config

claude mcp add bonsai-mcp -- uv --directory C:\Tools\bonsai-mcp run python -m bonsai_mcp

Verify:

claude mcp list

7. Usage procedure

7.1. Without Blender

1. ifc_open — open the file; check schema, units and element counts.
2. ifc_list_property_names — always run this before writing any property query.
3. ifc_model_info or ifc_spatial_tree — get the storey structure and per-class counts.
4. ifc_list_entities / ifc_select — filter to the elements you need; page with limit + offset.
5. ifc_get_element — full detail for one element.
6. ifc_geometry_info — geometry, profile and absolute placement of that element.
7. ifc_representation_stats / ifc_validate — whole-file QC.

7.2. With Blender

1. Load Project in Bonsai, then Start Server in the Bonsai MCP panel.
2. bl_status — confirm the file, the versions, and that the session switched to blender mode.
3. From here every ifc_* tool reads the model Blender holds. Do not call ifc_open — it is refused by design.
4. bl_set_view for an overview, bl_focus_element(guid) for one element.
5. For anything internal pass isolate=true, or use bl_isolate, then bl_isolate(restore=true).

8. Tool reference

8.1. IFC read tools

Query syntax for ifc_select:

IfcWall
IfcWall, IfcSlab
IfcBeam, Name=/B-.*/
IfcSpace, Pset_SpaceCommon.IsExternal=TRUE

8.2. Blender tools

direction: front, back, left, right, top, bottom, axo.

width bounds the image's longest side, not literally its width. The viewport aspect ratio is preserved. Clamped to 320–2048.

bl_reload does not reload from disk; it rebuilds the viewport from the in-memory IFC data.

8.3. Edit tools, group A: attributes

No geometry is touched. Each takes guid for one element or query for many.

8.4. Edit tools, group B: placement

ifc_rotate_element spins the element about its own origin, not the project origin.

8.5. Edit tools, group C: parametric geometry

Recipes: ResetAbsoluteCoordinates, OffsetObjectPlacements, SetWorldCoordinateSystem, ConvertLengthUnit, Optimise.

args uses the recipe's own parameter names; a wrong name is answered with the accepted list and their defaults.

8.6. Saving

9. Safe editing procedure

1. Run ifc_geometry_info before any geometry edit — check the real parameter names and whether the element shares a representation map.
2. Edit. The session's first edit automatically writes <name>.backup-<timestamp>.ifc beside the original.
3. Read the before/after values in the result. Every edit tool returns both.
4. In blender mode, use bl_focus_element or bl_screenshot to look at the result. The viewport is already resynced.
5. ifc_save to a new path. Overwriting requires an explicit overwrite=true.
6. If it went wrong, ifc_revert returns to the state before the first edit.

Guardrails

Note: Blender's own undo (Ctrl+Z) does not cover MCP edits. Use ifc_revert.

10. Unit conventions

The placement matrix is absolute: the whole nested IfcLocalPlacement chain is multiplied through.

11. Environment variables

12. Troubleshooting

Blender

Editing

13. Development

uv sync
uv run python -m pytest -v
uv run python -m bonsai_mcp --selfcheck

Conventions:

• uv.lock is committed; .venv/ never is.
• No print(). stdout is the JSON-RPC channel; log through config.py to stderr.
• Nothing in src/ may import bpy — the server must run with Blender closed. A test enforces it.
• addon/bonsai_mcp_addon/protocol.py runs on the socket thread and must never touch bpy; all bpy calls live in handlers.py and run only from the main-thread timer. bpy is not thread safe — a call from the wrong thread crashes Blender dozens of commands later, somewhere unrelated. An AST test enforces it.
• Failing tools return the full traceback in the traceback field; Blender-side failures carry Blender's own traceback too.
• Every write goes through ifcopenshell.api, and through Session.write; no tool touches the model directly.
• There are no raw-mesh tools. Editing a mesh freely and writing it back turns a SweptSolid into a Tessellation — parameters gone, file inflated, recipient unable to edit. A test enforces it.
• The guardrail fixture is generated by tests/steel_fixture.py: 4 beams sharing one IfcRepresentationMap, 1 column with its own profile, 1 tessellated slab.

License: MIT — see LICENSE.