How israel-romero-fijo/blender-mcp works
Project Type and Purpose
• The project is designed as an integration tool between Blender and Claude AI. Its purpose is to allow Claude to command Blender for tasks like 3D modeling, scene manipulation, and asset management.
• The two primary components identified in the README are the Blender addon (addon.py) and the MCP server (src/blender_mcp/server.py), which together form a client/server model communicating over a socket with a simple JSON-based protocol.
File Structure
• Top-level files include configuration files (.gitignore, LICENSE, pyproject.toml), documentation (README.md), and main executable scripts (addon.py, main.py). The presence of a “src” directory indicates modular code separation.
• Under “src/blender_mcp” you find the server-related code, specifically server.py which implements the Model Context Protocol.
• The “assets” directory holds images for instructions and UI elements that are referenced in the README.
• The file tree suggests a relatively lean project with the Blender addon as one entry point (to be integrated into Blender) and a separate MCP server for external communication.
README for Insights
• The README details the two-way communication using TCP sockets and JSON messages, emphasizing commands for object and scene manipulation.
• It also explains external integrations such as Poly Haven and Hyper3D Rodin, which, while optional, represent additional external data sources or services.
a. Main Components:
• Blender Application with the Blender Addon (addon.py)
– Represent this as a block labeled “Blender Application” with a sub-component “Blender Addon.”
– Highlight that the addon sets up a socket server in Blender for receiving commands.
• MCP Server (src/blender_mcp/server.py)
– Create a separate block for the “MCP Server.”
– Note that it implements the control protocol and is responsible for relaying commands and responses.
• External Clients and Services:
– Optionally include “Poly Haven API” and “Hyper3D Rodin” as external services used for assets and AI-generated models.
b. Relationships and Interactions:
– From Claude AI to the MCP Server (commands are relayed).
– From the MCP Server to the Blender Addon (commands are sent over TCP using a JSON protocol).
c. Architectural Patterns and Design Details:
• Client-server pattern: The MCP Server and the Blender Addon communicate over a socket using a JSON-based messaging system.
• “Two-Way Communication” and “Socket-Based Communication” as central design principles.
• The separation between the user interface in Blender and the server running separately reinforces modularity.
d. Specific Technologies and Frameworks:
• Mention Python as the implementation language.
• References to uv (the package manager) which is used to run the MCP Server.
• That the communication protocol is JSON over TCP sockets.
Elements
• Clear labels for each component block:
– “Blender Application” with sub-label “Blender Addon (addon.py)”
– “MCP Server (server.py)”
– “Claude AI (Desktop Interface)”
– Optionally, “Poly Haven API” and “Hyper3D Rodin Integration”
• Visual Differentiation:
– Optionally, add annotations to indicate protocols (TCP, JSON) and roles (command sender, command executor).
Summary
• Every component is clearly defined, and the interactions (data flows, dependencies) between components are meticulously represented.