# ahujasid/blender-mcp architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source integration tool (“BlenderMCP”) that connects Blender (a 3D modeling application) to Claude AI via the Model Context Protocol (MCP). It consists of a Blender addon and a standalone Python MCP server.

##### File structure
Top-level files and directories:
- addon.py    – Blender addon script that runs inside Blender
- main.py    – entry point for the CLI tool (“blender-mcp”)
- assets/    – screenshots and UI instruction images
- src/blender_mcp/server.py – MCP server implementation
- pyproject.toml, uv.lock – build/runtime configuration

Patterns and configuration:
- addon.py loads a socket server in Blender.
- server.py listens for MCP commands and forwards them over TCP.
- The CLI (uvx command) launches main.py → server.py.

##### Extract architectural insights from README
– Two-way JSON-over-TCP protocol (“type”/“params” commands, “status”/“result” responses).
– External integrations:
- Claude AI (as an MCP client)
- Poly Haven assets API
- Hyper3D Rodin API
– User workflows: Blender UI → socket → MCP server → Claude and back.

##### Main components and interactions
a. Components
1. Blender Application
– BlenderMCP Addon (addon.py)
– UI in 3D View sidebar
– Local TCP socket listener (e.g., localhost:port)
2. MCP Server Process
– CLI entry (uvx → main.py)
– server.py implements protocol, manages sockets
3. Claude AI Desktop/Cursor
– Configured as an MCP client pointing to “blender-mcp”
4. External Services
– Poly Haven API
– Hyper3D Rodin API
b. Relationships and data flow
1. User clicks “Connect” in Blender → addon.py starts the socket server
2. MCP Server (CLI) registers with Claude → Claude sends JSON commands
3. server.py forwards commands over TCP to Blender addon
4. Blender executes commands (object creation, material changes, code exec)
5. Results/responses are sent back over the same TCP channel → MCP server → Claude
6. For asset/model requests, MCP server or addon calls out to Poly Haven / Hyper3D endpoints
c. Architectural patterns / design principles
– Separation of concerns: Blender-embedded addon vs. external protocol server
– Simple JSON-over-TCP protocol for interoperability
– CLI wrapper (uvx) for process management
– Extensibility via external service adapters (APIs)
d. Key technologies
– Python 3.10+
– TCP sockets, JSON serialization
– Blender Python API (bpy)
– uv (Astral UV package manager to publish “blender-mcp” CLI)

2. “Blender + addon.py” in one tier; show internal socket listener.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Layers
    subgraph "AI Client Layer"
        Claude["Claude AI\n(MCP Client)"]:::ai
    end

    subgraph "Protocol/Server Layer"
        CLI["CLI Entry: main.py\n(uvx)"]:::server
        MCP["MCP Server\n(server.py)"]:::server
        Init["Package Init\n(__init__.py)"]:::server
        Config["Config: pyproject.toml"]:::server
    end

    subgraph "Blender Application Layer"
        Addon["BlenderMCP Addon\n(addon.py, bpy)"]:::frontend
        Assets["UI Assets\n(assets/)"]:::frontend
    end

    subgraph "External Services"
        PH["Poly Haven API"]:::external
        H3["Hyper3D Rodin API"]:::external
    end

    %% Data Flows
    Claude -->|"JSON Command(type,params)"| CLI
    CLI -->|"launch server"| MCP
    MCP -->|"JSON Command over TCP"| Addon
    Addon -->|"JSON Response over TCP"| MCP
    MCP -->|"JSON Response(status,result)"| Claude

    MCP -->|"HTTP REST calls for assets/models"| PH
    Addon -->|"HTTP REST calls for assets/models"| PH
    MCP -->|"HTTP REST calls for assets/models"| H3
    Addon -->|"HTTP REST calls for assets/models"| H3

    %% Click Events
    click Addon "https://github.com/ahujasid/blender-mcp/blob/main/addon.py"
    click Assets "https://github.com/ahujasid/blender-mcp/tree/main/assets/"
    click CLI "https://github.com/ahujasid/blender-mcp/blob/main/main.py"
    click MCP "https://github.com/ahujasid/blender-mcp/blob/main/src/blender_mcp/server.py"
    click Config "https://github.com/ahujasid/blender-mcp/blob/main/pyproject.toml"
    click Init "https://github.com/ahujasid/blender-mcp/blob/main/src/blender_mcp/__init__.py"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6
    classDef server fill:#DFFFE0,stroke:#28a745
    classDef ai fill:#FFEFD5,stroke:#d2691e
    classDef external fill:#f0e0ff,stroke:#6f42c1
```
