Blender

BlenderMCP: AI-Powered 3D Creation

BlenderMCP integrates Blender with Claude AI via the Model Context Protocol (MCP), enabling AI-driven 3D scene creation, modeling, and manipulation. This project allows users to control Blender directly through natural language prompts, streamlining the 3D design workflow.

How to Use BlenderMCP

To use BlenderMCP, you need to set up both the MCP server and the Blender addon.

Prerequisites:

• Blender 3.0 or newer
• Python 3.10 or newer
• uv package manager (install via brew install uv on Mac, or PowerShell script on Windows).

Claude for Desktop Integration:

1. Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json.
2. Add the following configuration to mcpServers:

   {
       "mcpServers": {
           "blender": {
               "command": "uvx",
               "args": [
                   "blender-mcp"
               ]
           }
       }
   }
   

Cursor Integration:

• For Mac: Go to Settings > MCP and use "add new global MCP server" or create .cursor/mcp.json in your project root and paste the above JSON configuration.
• For Windows: Go to Settings > MCP > Add Server and add a new server with the same configuration, but change the command to "cmd" and add "/c" before "uvx".

Installing the Blender Addon:

1. Download the addon.py file from the BlenderMCP repository.
2. Open Blender, go to Edit > Preferences > Add-ons.
3. Click "Install..." and select the addon.py file.
4. Enable the addon by checking the box next to "Interface: Blender MCP".

Starting the Connection in Blender:

1. In Blender, go to the 3D View sidebar (press N).
2. Find the "BlenderMCP" tab.
3. Optionally, turn on the Poly Haven checkbox.
4. Click "Connect to Claude".
5. Ensure the MCP server is running in your terminal.

Once connected, you will see a hammer icon in Claude with tools for BlenderMCP, allowing you to interact with Blender using natural language.

Key Features of BlenderMCP

• Two-way communication: Establishes a socket-based server for Claude AI to interact with Blender.
• Object manipulation: Create, modify, and delete 3D objects.
• Material control: Apply and modify materials and colors.
• Scene inspection: Get detailed information about the current Blender scene.
• Code execution: Run arbitrary Python code in Blender from Claude.
• Asset integration: Support for Poly Haven assets and AI-generated 3D models using Hyper3D Rodin.
• View screenshots: View screenshots from Blender viewport to better understand the scene.
• Sketchfab integration: Search and download Sketchfab models.

Use Cases of BlenderMCP

BlenderMCP can be used for various 3D creation tasks, including:

• Rapid scene prototyping: Quickly generate complex 3D scenes with natural language prompts (e.g., "Create a low poly scene in a dungeon, with a dragon guarding a pot of gold").
• Asset integration: Easily incorporate assets from Poly Haven or generate new 3D models with Hyper3D.
• Material and lighting adjustments: Modify object materials and lighting conditions with simple commands (e.g., "Make this car red and metallic," "Make the lighting like a studio").
• Automated tasks: Execute custom Python code in Blender through Claude for advanced automation.
• Creative exploration: Experiment with different scene compositions and styles by describing them to the AI.
• Reference image to 3D scene: Create a Blender scene from a given reference image.
• 3D model generation: Generate 3D models using Hyper3D (e.g., "Generate a 3D model of a garden gnome through Hyper3D").
• Scene information and export: Get scene and object information and create a threejs sketch from it.

FAQ about BlenderMCP

Q: What are the main components of BlenderMCP? A: The system consists of two main components: the Blender Addon (addon.py), which creates a socket server in Blender, and the MCP Server (src/blender_mcp/server.py), which implements the Model Context Protocol and connects to the Blender addon.

Q: How do I troubleshoot connection issues? A: Ensure the Blender addon server is running and the MCP server is correctly configured on Claude. Do not run the uvx command in the terminal if you are using Claude or Cursor integration. Sometimes, the first command might not go through, but subsequent commands should work. If issues persist, try restarting both Claude and the Blender server.

Q: What are the limitations and security considerations? A: The execute_blender_code tool allows running arbitrary Python code, which can be powerful but potentially dangerous. Always save your work before using it. Poly Haven integration requires downloading models, textures, and HDRI images, which can be toggled off. Complex operations might need to be broken down into smaller steps.

Q: Can I use both Cursor and Claude Desktop for MCP server? A: No, you should only run one instance of the MCP server (either on Cursor or Claude Desktop), not both.

Q: What is Hyper3D integration? A: Hyper3D allows you to generate 3D models. The free trial key has a limited number of generations per day. You can obtain your own key from hyper3d.ai and fal.ai for more generations.

BlenderMCP - Blender Model Context Protocol Integration

BlenderMCP connects Blender to Claude AI through the Model Context Protocol (MCP), allowing Claude to directly interact with and control Blender. This integration enables prompt assisted 3D modeling, scene creation, and manipulation.

Full tutorial

Join the Community

Give feedback, get inspired, and build on top of the MCP: Discord

Supporters

Warp, the intelligent terminal for developers

Available for MacOS, Linux, & Windows

Other supporters:

CodeRabbit

All supporters:

Support this project

Release notes (1.2.0)

• View screenshots for Blender viewport to better understand the scene
• Search and download Sketchfab models

Previously added features:

• Support for Poly Haven assets through their API
• Support to generate 3D models using Hyper3D Rodin
• For newcomers, you can go straight to Installation. For existing users, see the points below
• Download the latest addon.py file and replace the older one, then add it to Blender
• Delete the MCP server from Claude and add it back again, and you should be good to go!

Features

• Two-way communication: Connect Claude AI to Blender through a socket-based server
• Object manipulation: Create, modify, and delete 3D objects in Blender
• Material control: Apply and modify materials and colors
• Scene inspection: Get detailed information about the current Blender scene
• Code execution: Run arbitrary Python code in Blender from Claude

Components

The system consists of two main components:

1. Blender Addon (addon.py): A Blender addon that creates a socket server within Blender to receive and execute commands
2. MCP Server (src/blender_mcp/server.py): A Python server that implements the Model Context Protocol and connects to the Blender addon

Installation

Prerequisites

• Blender 3.0 or newer
• Python 3.10 or newer
• uv package manager:

If you're on Mac, please install uv as

brew install uv

On Windows

powershell -c "irm https://astral.sh/uv/install.ps1 | iex" 

and then

set Path=C:\Users\nntra\.local\bin;%Path%

Otherwise installation instructions are on their website: Install uv

⚠️ Do not proceed before installing UV

Claude for Desktop Integration

Watch the setup instruction video (Assuming you have already installed uv)

Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": [
                "blender-mcp"
            ]
        }
    }
}

Cursor integration

For Mac users, go to Settings > MCP and paste the following

• To use as a global server, use "add new global MCP server" button and paste
• To use as a project specific server, create .cursor/mcp.json in the root of the project and paste

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": [
                "blender-mcp"
            ]
        }
    }
}

For Windows users, go to Settings > MCP > Add Server, add a new server with the following settings:

{
    "mcpServers": {
        "blender": {
            "command": "cmd",
            "args": [
                "/c",
                "uvx",
                "blender-mcp"
            ]
        }
    }
}

Cursor setup video

⚠️ Only run one instance of the MCP server (either on Cursor or Claude Desktop), not both

Installing the Blender Addon

1. Download the addon.py file from this repo
2. Open Blender
3. Go to Edit > Preferences > Add-ons
4. Click "Install..." and select the addon.py file
5. Enable the addon by checking the box next to "Interface: Blender MCP"

Usage

Starting the Connection

1. In Blender, go to the 3D View sidebar (press N if not visible)
2. Find the "BlenderMCP" tab
3. Turn on the Poly Haven checkbox if you want assets from their API (optional)
4. Click "Connect to Claude"
5. Make sure the MCP server is running in your terminal

Using with Claude

Once the config file has been set on Claude, and the addon is running on Blender, you will see a hammer icon with tools for the Blender MCP.

Capabilities

• Get scene and object information
• Create, delete and modify shapes
• Apply or create materials for objects
• Execute any Python code in Blender
• Download the right models, assets and HDRIs through Poly Haven
• AI generated 3D models through Hyper3D Rodin

Example Commands

Here are some examples of what you can ask Claude to do:

• "Create a low poly scene in a dungeon, with a dragon guarding a pot of gold" Demo
• "Create a beach vibe using HDRIs, textures, and models like rocks and vegetation from Poly Haven" Demo
• Give a reference image, and create a Blender scene out of it Demo
• "Generate a 3D model of a garden gnome through Hyper3D"
• "Get information about the current scene, and make a threejs sketch from it" Demo
• "Make this car red and metallic"
• "Create a sphere and place it above the cube"
• "Make the lighting like a studio"
• "Point the camera at the scene, and make it isometric"

Hyper3D integration

Hyper3D's free trial key allows you to generate a limited number of models per day. If the daily limit is reached, you can wait for the next day's reset or obtain your own key from hyper3d.ai and fal.ai.

Troubleshooting

• Connection issues: Make sure the Blender addon server is running, and the MCP server is configured on Claude, DO NOT run the uvx command in the terminal. Sometimes, the first command won't go through but after that it starts working.
• Timeout errors: Try simplifying your requests or breaking them into smaller steps
• Poly Haven integration: Claude is sometimes erratic with its behaviour
• Have you tried turning it off and on again?: If you're still having connection errors, try restarting both Claude and the Blender server

Technical Details

Communication Protocol

The system uses a simple JSON-based protocol over TCP sockets:

• Commands are sent as JSON objects with a type and optional params
• Responses are JSON objects with a status and result or message

Limitations & Security Considerations

• The execute_blender_code tool allows running arbitrary Python code in Blender, which can be powerful but potentially dangerous. Use with caution in production environments. ALWAYS save your work before using it.
• Poly Haven requires downloading models, textures, and HDRI images. If you do not want to use it, please turn it off in the checkbox in Blender.
• Complex operations might need to be broken down into smaller steps

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Disclaimer

This is a third-party integration and not made by Blender. Made by Siddharth