How ahujasid/blender-mcp works
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.