Blender MCP Server

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

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:

   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:

   {
     "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:

   class MyToolInput(BaseModel):
       param: str = Field(...)
   

2. Add operation in src/operations.py:

   def my_operation(input: MyToolInput) -> str:
       # Blender code here
       return "Success: ..."
   

3. Add tool in src/tools.py:

   @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)