# dhakalnirajan/blender-open-mcp architecture

> Architecture diagram of the GitHub repository dhakalnirajan/blender-open-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dhakalnirajan/blender-open-mcp
- Repository: https://github.com/dhakalnirajan/blender-open-mcp

## Overview

##### Project Type & Purpose
- This is an open-source Blender add-on that integrates Blender with local AI models (via Ollama) using the Model Context Protocol (MCP). The goal is to control Blender with natural language commands to assist with 3D modeling tasks.
- The project leverages both a server component (the MCP server) and a Blender-side add-on (addon.py) for seamless integration, while also optionally interacting with external asset sources like PolyHaven.

##### Analyzing the File Structure
- Top-Level Files:
- addon.py: The Blender add-on script providing the user interface inside Blender.
- main.py: Likely an entry point or auxiliary script.
- pyproject.toml, .python-version, LICENSE, and README.md: Configuration, versioning, documentation, and licensing files.
- uv.lock and .gitignore support dependency management and version control.
- The src Directory:
- Contains the package (blender_open_mcp) with files like __init__.py (initializes the package) and server.py (the core server functionality).

##### Components
- Blender Client:
- Represented by the Blender add-on (addon.py). This is the primary interface through which users trigger actions, view panels, and receive information.
- MCP Server:
- Represented by the code inside src/blender_open_mcp, particularly server.py. This server handles incoming commands from the Blender add-on (or from command line tools like “mcp”) and translates them into actions through the MCP.
- External AI Model (Ollama):
- An external dependency that runs locally. The MCP server sends prompts and receives responses from the Ollama model.
- Optional External Services:
- PolyHaven: If enabled, commands from the client might trigger asset downloads or other operations via PolyHaven integration.

##### Main Relationships & Data Flow
- User interactions in Blender (or via a CLI “mcp” tool) issue commands that need to be forwarded to the MCP server.
- The MCP server receives these commands, processes them, and connects with the local Ollama model to interpret natural language prompts.
- Depending on the command, the server instructs Blender to perform actions (like creating, modifying, or deleting objects, setting materials, or rendering images).
- There is also potential data flow from the MCP server to PolyHaven if asset retrieval is requested.
- Blender Add-on → MCP Server (command initiation)
- MCP Server → Ollama Model (for AI processing)
- MCP Server → Blender (execution of Blender operations)
- Optionally, MCP Server → PolyHaven API (when asset-related commands are issued)

##### Architectural Patterns & Technologies
- The project uses a client-server model, with separation between the user interface (Blender add-on) and the logic processor (MCP server).
- The system utilizes the Model Context Protocol (MCP) as an abstraction layer for structuring communication.
- It integrates with external services (Ollama for AI prompts and PolyHaven for assets), indicating a design that supports modular integrations.
- Additionally, the use of Python (with files like main.py and pyproject.toml) and third-party libraries like “uv” is central to the backend component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Blender Components
    subgraph "Blender Components"
        BLENDER["Blender Add-on Interface"]:::frontend
        CLI["CLI Tool (mcp)"]:::cli
    end

    %% MCP Server Components
    subgraph "MCP Server"
        INIT["MCP Server Package Init (__init__.py)"]:::server
        SERVER["MCP Server (server.py) [http://0.0.0.0:8000]"]:::server
    end

    %% External Services
    OLLAMA["Ollama AI Model"]:::external
    POLY["PolyHaven Asset Service"]:::external

    %% Relationships
    BLENDER -->|"command"| SERVER
    CLI -->|"command"| SERVER
    SERVER -->|"processes"| OLLAMA
    SERVER -->|"feedback"| BLENDER
    SERVER -->|"asset_request"| POLY
    INIT --> SERVER

    %% Click Events
    click BLENDER "https://github.com/dhakalnirajan/blender-open-mcp/blob/main/addon.py"
    click CLI "https://github.com/dhakalnirajan/blender-open-mcp/blob/main/main.py"
    click SERVER "https://github.com/dhakalnirajan/blender-open-mcp/blob/main/src/blender_open_mcp/server.py"
    click INIT "https://github.com/dhakalnirajan/blender-open-mcp/blob/main/src/blender_open_mcp/__init__.py"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,stroke-width:2px
    classDef cli fill:#D5F5E3,stroke:#27AE60,stroke-width:2px
    classDef server fill:#F1948A,stroke:#C0392B,stroke-width:2px
    classDef external fill:#F9E79F,stroke:#F1C40F,stroke-width:2px
```
