Bonsai MCP

🚀 Bonsai-mcp - Integration of Blender Model Context Protocol with IFC via IfcOpenShell

Bonsai-mcp is a fork of BlenderMCP, extending its functionality and providing specialized support for IFC (Industry Foundation Classes) models through Bonsai. This integration is a rapid proof-of-concept, aiming to demonstrate the ability to connect Claude (or other LLMs, although only the Claude Desktop Client has been tested here) to Blender to execute IfcOpenShell commands.

✨ Features

• IFC-specific Features: Query IFC models, analyze spatial structures, and examine building elements.
• Five Powerful IFC Tools: View project information, list entities, check attributes, explore spatial structures, and analyze relationships.
• Sequential Thinking Tools: Sequential thinking tools from modelcontextprotocol/servers for structured problem-solving.
• Code Execution Tools (from the original BlenderMCP implementation): Create and modify objects, apply materials, and execute Python code in Blender.
• Validated Standard Models: Compatible with the default ifcopenshell house model.

🔧 Technical Details

The IFC integration uses the Bonsai BIM module to access IfcOpenShell functionality. Communication follows the same JSON-based protocol as the original BlenderMCP, conducted via TCP sockets.

📚 Documentation

The bonsai-mcp project is divided into two main parts:

1. server: Responsible for handling requests from clients (such as Claude) and executing corresponding operations.
2. client: Used to communicate with the server and send instructions to control operations in Blender.

📦 Installation

To use Bonsai-mcp, follow these installation and configuration steps:

1. Install Dependencies

Ensure the following software is installed:

• Blender (recommended version 3.x)
• Python (recommended version 3.8 or higher)
• IfcOpenShell
• Bonsai BIM plugin

2. Clone the Repository

git clone https://github.com/yourusername/bonsai-mcp.git
cd bonsai-mcp

3. Install Python Packages

Install the required Python packages:

pip install -r requirements.txt

4. Start the Server

Start the Bonsai-mcp server:

python server.py

5. Use the Client

Use the provided client script to interact with the server. For example, to send a message:

python client.py --message "Analyze this IFC model"

💻 Usage Examples

Here are some example commands demonstrating how to operate through Bonsai-mcp:

Basic Usage

• Query Model Information:

  python client.py --message "get_model_info"
  

• List All Entities:

  python client.py --message "list_entities"
  

Advanced Usage

• Execute Sequential Thinking Tools:

  python client.py --message "sequential_thinking analyze_building_energy_efficiency"
  

📄 License

Contributions are welcome! Please refer to the license file in the project repository for usage terms.

⚠️ Important Note

• Connection Issues: Ensure that the Blender plugin server is running and the MCP server in Claude is correctly configured.
• IFC Model Not Loaded: Verify that the Bonsai BIM plugin is installed and has loaded the IFC file.
• Timeout Errors: Try simplifying requests or breaking operations into smaller steps.