# ahujasid/mcp-for-blender architecture

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

- Interactive diagram: https://gitdiagram.com/ahujasid/mcp-for-blender
- Repository: https://github.com/ahujasid/mcp-for-blender
- Video tour (about a minute): https://gitdiagram.com/ahujasid/mcp-for-blender/video

## Overview

MCP for Blender connects an AI client to Blender through an MCP server and a Blender-hosted socket addon. The main workflow is a client tool request, server-side tool handling, socket command execution in Blender, and a result returned to the client. Documented capabilities include scene/object/material manipulation, inspection, code execution, and external asset/model generation. Setup, consent and privacy telemetry, app extensions, and trajectory capture are supporting runtime branches. Several feature-specific server internals are unsampled, so capability details rely on the README rather than inferred call chains.

Main entry points: [`src/blender_mcp/server.py`](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py) (MCP Server Tools), [`src/blender_mcp/telemetry_decorator.py`](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/telemetry_decorator.py) (Tool Instrumentation), [`src/blender_mcp/telemetry.py`](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/telemetry.py) (Usage Telemetry), [`addon.py`](https://github.com/ahujasid/mcp-for-blender/blob/main/addon.py) (Blender Addon)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connection["MCP Connection"]
  node_server["MCP Server Tools<br/>[server.py]"]
  node_socket["Blender Socket<br/>[server.py]"]
end

subgraph group_blender["Blender Operations"]
  node_addon["Blender Addon<br/>[addon.py]"]
  node_scene["Scene and Objects<br/>[server.py]"]
  node_materials["Materials and Colors<br/>[server.py]"]
  node_inspection["Scene Inspection<br/>[server.py]"]
  node_code["Code Execution<br/>[server.py]"]
  node_safety["Safe Mode Validator<br/>[safe_mode.py]"]
end

subgraph group_features["Creative Features"]
  node_asset_search["Asset Search<br/>[server.py]"]
  node_model_generation["Model Generation<br/>[server.py]"]
  node_apps["Client App Extensions<br/>[openai_apps.py]"]
  node_asset_services["Asset and Model Services"]
end

subgraph group_support["Setup and Guidance"]
  node_setup["Setup CLI<br/>[setup_cli.py]"]
  node_addon_manager["Addon Installer<br/>[addon_manager.py]"]
  node_premium["Premium Guidance<br/>[premium_hint.py]"]
end

subgraph group_observability["Privacy and Capture"]
  node_consent["Telemetry Consent<br/>[consent_prompt.py]"]
  node_telemetry["Usage Telemetry<br/>[telemetry.py]"]
  node_decorator["Tool Instrumentation"]
  node_trajectory["Trajectory Capture<br/>[trajectory.py]"]
  node_supabase[("Supabase")]
end

node_client(("AI Client"))

node_client -->|"requests tools"| node_server
node_server -->|"sends commands"| node_socket
node_socket -->|"socket commands"| node_addon
node_addon -->|"returns results"| node_client
node_server -->|"provides tools"| node_scene
node_server -->|"provides tools"| node_materials
node_server -->|"provides tools"| node_inspection
node_server -->|"provides tools"| node_code
node_server -->|"validates code"| node_safety
node_server -->|"provides tools"| node_asset_search
node_server -->|"provides tools"| node_model_generation
node_asset_search -->|"searches assets"| node_asset_services
node_model_generation -->|"requests models"| node_asset_services
node_server -->|"uses extensions"| node_apps
node_setup -->|"installs addon"| node_addon_manager
node_server -->|"checks handshake"| node_addon_manager
node_server -->|"adds guidance"| node_premium
node_server -->|"requests consent"| node_consent
node_consent -->|"writes consent"| node_socket
node_decorator -->|"wraps tools"| node_server
node_decorator -->|"records events"| node_telemetry
node_decorator -->|"records steps"| node_trajectory
node_telemetry -->|"checks consent"| node_socket
node_telemetry -->|"sends events"| node_supabase
node_trajectory -->|"persists captures"| node_supabase

click node_server "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py"
click node_socket "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py"
click node_addon "https://github.com/ahujasid/mcp-for-blender/blob/main/addon.py"
click node_scene "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py"
click node_materials "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py"
click node_inspection "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py"
click node_code "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py"
click node_safety "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/safe_mode.py"
click node_asset_search "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py"
click node_model_generation "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py"
click node_apps "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/openai_apps.py"
click node_setup "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/setup_cli.py"
click node_addon_manager "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/addon_manager.py"
click node_premium "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/premium_hint.py"
click node_consent "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/consent_prompt.py"
click node_telemetry "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/telemetry.py"
click node_decorator "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/telemetry_decorator.py"
click node_trajectory "https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/trajectory.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_socket,node_client toneBlue
class node_addon,node_scene,node_materials,node_inspection,node_code,node_safety toneAmber
class node_asset_search,node_model_generation,node_apps,node_asset_services toneMint
class node_setup,node_addon_manager,node_premium toneRose
class node_consent,node_telemetry,node_decorator,node_trajectory,node_supabase toneIndigo
```

## Components

### MCP Connection

- [MCP Server Tools](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py): `src/blender_mcp/server.py`
- [Blender Socket](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py): `src/blender_mcp/server.py`

### Blender Operations

- [Blender Addon](https://github.com/ahujasid/mcp-for-blender/blob/main/addon.py): `addon.py`
- [Scene and Objects](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py): `src/blender_mcp/server.py`
- [Materials and Colors](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py): `src/blender_mcp/server.py`
- [Scene Inspection](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py): `src/blender_mcp/server.py`
- [Code Execution](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py): `src/blender_mcp/server.py`
- [Safe Mode Validator](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/safe_mode.py): `src/blender_mcp/safe_mode.py`

### Creative Features

- [Asset Search](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py): `src/blender_mcp/server.py`
- [Model Generation](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/server.py): `src/blender_mcp/server.py`
- [Client App Extensions](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/openai_apps.py): `src/blender_mcp/openai_apps.py`
- **Asset and Model Services**

### Setup and Guidance

- [Setup CLI](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/setup_cli.py): `src/blender_mcp/setup_cli.py`
- [Addon Installer](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/addon_manager.py): `src/blender_mcp/addon_manager.py`
- [Premium Guidance](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/premium_hint.py): `src/blender_mcp/premium_hint.py`

### Privacy and Capture

- [Telemetry Consent](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/consent_prompt.py): `src/blender_mcp/consent_prompt.py`
- [Usage Telemetry](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/telemetry.py): `src/blender_mcp/telemetry.py`
- [Tool Instrumentation](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/telemetry_decorator.py): `src/blender_mcp/telemetry_decorator.py`
- [Trajectory Capture](https://github.com/ahujasid/mcp-for-blender/blob/main/src/blender_mcp/trajectory.py): `src/blender_mcp/trajectory.py`
- **Supabase**

### Other components

- **AI Client**

## Connections

- AI Client → MCP Server Tools: requests tools (evidence: `README.md`)
- MCP Server Tools → Blender Socket: sends commands (evidence: `src/blender_mcp/server.py`)
- Blender Socket → Blender Addon: socket commands (evidence: `README.md`)
- Blender Addon → AI Client: returns results (evidence: `README.md`)
- MCP Server Tools → Scene and Objects: provides tools (evidence: `README.md`)
- MCP Server Tools → Materials and Colors: provides tools (evidence: `README.md`)
- MCP Server Tools → Scene Inspection: provides tools (evidence: `README.md`)
- MCP Server Tools → Code Execution: provides tools (evidence: `README.md`)
- MCP Server Tools → Safe Mode Validator: validates code (evidence: `src/blender_mcp/safe_mode.py`)
- MCP Server Tools → Asset Search: provides tools (evidence: `README.md`)
- MCP Server Tools → Model Generation: provides tools (evidence: `README.md`)
- Asset Search → Asset and Model Services: searches assets (evidence: `README.md`)
- Model Generation → Asset and Model Services: requests models (evidence: `README.md`)
- MCP Server Tools → Client App Extensions: uses extensions (evidence: `src/blender_mcp/server.py`)
- Setup CLI → Addon Installer: installs addon (evidence: `src/blender_mcp/setup_cli.py`)
- MCP Server Tools → Addon Installer: checks handshake (evidence: `src/blender_mcp/server.py`)
- MCP Server Tools → Premium Guidance: adds guidance (evidence: `src/blender_mcp/server.py`)
- MCP Server Tools → Telemetry Consent: requests consent (evidence: `src/blender_mcp/server.py`)
- Telemetry Consent → Blender Socket: writes consent (evidence: `src/blender_mcp/consent_prompt.py`)
- Tool Instrumentation → MCP Server Tools: wraps tools (evidence: `src/blender_mcp/server.py`)
- Tool Instrumentation → Usage Telemetry: records events (evidence: `src/blender_mcp/telemetry_decorator.py`)
- Tool Instrumentation → Trajectory Capture: records steps (evidence: `src/blender_mcp/telemetry_decorator.py`)
- Usage Telemetry → Blender Socket: checks consent (evidence: `src/blender_mcp/telemetry.py`)
- Usage Telemetry → Supabase: sends events (evidence: `src/blender_mcp/telemetry.py`)
- Trajectory Capture → Supabase: persists captures (evidence: `src/blender_mcp/trajectory.py`)