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

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

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

Error Flow