## View the Demo Here!
https://drive.google.com/file/d/1VHnKps0HPqw4ipIw1GG_X68u8iuSRbCK/view
## Prerequisites
Before you begin, make sure you have:
- **Python 3.13+** installed
- **Blender 5.0+** installed at `/Applications/Blender.app/Contents/MacOS/Blender` (macOS)
- For Linux/Windows: Update the `blender_path` in `blender_mcp_filter.py`
- **Claude Desktop** installed (for AI agent integration)
## How to Install Dependencies
```bash
cd /path/to/blender_takehome
pip install -e .
```
This installs:
- `fastmcp>=2.12.4` - MCP server framework
- `pydantic>=2.0.0` - Input validation
- `fake-bpy-module-latest` - Type stubs for development
## How to Run the Server
This is the easiest way to use the server with Claude Desktop:
1. **Copy the configuration file**:
```bash
cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
2. **Edit the configuration file** and update the paths to match your project location:
```json
{
"mcpServers": {
"blender-server": {
"command": "python3",
"args": [
"/YOUR/PATH/TO/blender_takehome/blender_mcp_filter.py"
],
"env": {
"PYTHONPATH": "/YOUR/PATH/TO/blender_takehome:/YOUR/PATH/TO/blender_takehome/src"
}
}
}
}
```
3. **Now Open Blender** -- the Blender MCP server will automatically be running now.
4. **Restart Claude Desktop** - it will automatically launch the Blender MCP server when you start a conversation.
5. **Start Experimenting**: Ask Claude to create a cube in Blender. You should see Blender open and a cube appear!
## List of Tools Implemented
The server provides 22 tools organized into the following categories:
### Object Creation (5 tools)
- `create_cube_tool` - Create a cube primitive
- `create_sphere_tool` - Create a UV sphere primitive
- `create_cylinder_tool` - Create a cylinder primitive
- `create_plane_tool` - Create a plane primitive
- `duplicate_object_tool` - Duplicate an existing object
### Object Manipulation (5 tools)
- `move_object_tool` - Move an object to a new location
- `rotate_object_tool` - Rotate an object
- `scale_object_tool` - Scale an object
- `delete_object_tool` - Delete an object from the scene
- `select_object_tool` - Select an object in the scene
### Scene Management (3 tools)
- `list_objects_tool` - List all objects in the scene
- `get_object_info_tool` - Get detailed information about an object
- `clear_scene_tool` - Remove all objects from the scene
### Camera Operations (1 tool)
- `set_active_camera_tool` - Set the active camera for rendering
### Materials (2 tools)
- `create_material_tool` - Create a new material with a base color
- `assign_material_tool` - Assign a material to an object
### Rendering (3 tools)
- `create_camera_tool` - Create and configure a camera
- `create_light_tool` - Create a light source
- `render_scene_tool` - Render the scene to an image file
### File Operations (3 tools)
- `get_scene_filepath_tool` - Get the current Blender file path
- `save_file_tool` - Save the scene to a file
- `open_file_tool` - Open an existing Blender file
## Usage Examples
Once connected to Claude Desktop, you can ask Claude to:
- "Create a red cube at position (2, 0, 0)"
- "Add a sphere with radius 1.5"
- "Create a material called 'Metal' with color (0.8, 0.8, 0.9)"
- "Render the scene to /path/to/output.png"
- "List all objects in the scene"
- "Save the current file as "_______/Project.blend"
Claude will use the MCP tools to execute these commands in Blender.
## Project Structure
```
blender_takehome/
├── src/
│ ├── models.py # Pydantic input validation models
│ ├── operations.py # Pure Blender operations (bpy API)
│ ├── tools.py # MCP tool wrappers
│ └── server.py # FastMCP server setup
├── blender_mcp_filter.py # Launches Blender and filters stdout
├── blender_mcp_server.py # Entry point script for Blender
├── claude_desktop_config.json # Claude Desktop configuration
└── pyproject.toml # Python dependencies
```
## Design Choices
The server follows a three-layer architecture:
1. **Models** (`src/models.py`) - Pydantic models validate all inputs
2. **Operations** (`src/operations.py`) - Pure functions that interact with Blender's bpy API
3. **Tools** (`src/tools.py`) - MCP tool wrappers that expose operations to AI agents
I decided to separate this project into this three-layer architecture in order to isolate where errors were occuring very easily. This helped a lot in the debugging process. This has also simplified the creation of adding new tools within the MCP arsenal.
All that needs to be done to add a new tale is:
1. **Add model** in `src/models.py`:
```python
class MyToolInput(BaseModel):
param: str = Field(...)
```
2. **Add operation** in `src/operations.py`:
```python
def my_operation(input: MyToolInput) -> str:
# Blender code here
return "Success: ..."
```
3. **Add tool** in `src/tools.py`:
```python
@mcp.tool()
async def my_tool_tool(param: str) -> str:
input_model = MyToolInput(param=param)
return my_operation(input_model)
```
That's it! FastMCP automatically registers the tool.
### Tool Call Flow
```
1. Claude Desktop sends JSON-RPC request:
{"method": "tools/call", "params": {"name": "create_cube_tool", "arguments": {...}}}
2. FastMCP receives request, routes to create_cube_tool()
3. tools.py: create_cube_tool() validates input with CreateCubeInput
4. operations.py: create_cube() executes bpy.ops.mesh.primitive_cube_add()
5. Blender creates cube, updates scene
6. operations.py: Returns success message string
7. tools.py: Returns string to FastMCP
8. FastMCP sends JSON-RPC response:
{"result": {"content": [{"type": "text", "text": "Successfully created cube..."}]}}
9. Claude Desktop receives response
```
### Error Flow
```
1. Invalid input (e.g., size = -1.0)
2. Pydantic validation fails in models.py
3. ValidationError raised with clear message
4. tools.py catches exception, returns "Error: size must be > 0.001"
5. FastMCP sends error response to Claude Desktop
6. Server continues running (no crash)
```
