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.

We have no official website. Any website you see online is unofficial and has no affiliation with this project. Use them at your own risk.

Full tutorial

Join the Community

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

Supporters

CodeRabbit

All supporters:

Support this project

Release notes (1.4.0)

Added Hunyuan3D support

Previously added features:

View screenshots for Blender viewport to better understand the scene

Search and download Sketchfab models

Support for Poly Haven assets through their API

Support to generate 3D models using Hyper3D Rodin

Run Blender MCP on a remote host

Telemetry for tools executed (completely anonymous)

Installating a new version (existing users)

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

BASH

brew install uv

On Windows

POWERSHELL

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

and then add uv to the user path in Windows (you may need to restart Claude Desktop after):

POWERSHELL

$localBin = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User") [Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User")

Otherwise installation instructions are on their website: Install uv

⚠️ Do not proceed before installing UV

Environment Variables

The following environment variables can be used to configure the Blender connection:

BLENDER_HOST: Host address for Blender socket server (default: "localhost")

BLENDER_PORT: Port number for Blender socket server (default: 9876)

Example:

BASH

export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876

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:

JSON

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

Claude Code

Use the Claude Code CLI to add the blender MCP server:

BASH

claude mcp add blender uvx blender-mcp

Cursor integration

![Install MCP Server](https://cursor.com/install-mcp?name=blender&config=eyJjb21tYW5kIjoidXZ4IGJsZW5kZXItbWNwIn0%3D)

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

JSON

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

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

JSON

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

Visual Studio Code Integration

_Prerequisites_: Make sure you have Visual Studio Code installed before proceeding.

![Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22blender-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22blender-mcp%22%5D%7D)

Installing the Blender Addon

1. Download the addon.py file from this repo 1. Open Blender 2. 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"

Usage

Starting the Connection

!BlenderMCP in the sidebar

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.

!BlenderMCP in the sidebar

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

About

BlenderMCP is an open-source integration that connects Blender (3D modeling software) to Claude AI using the Model Context Protocol (MCP). It allows you to control and manipulate Blender scenes through conversational AI prompts, enabling tasks like object creation, material editing, and scene inspection via natural language commands from within Claude. The project is a third-party tool, not officially affiliated with Blender.

16 files

3 folders

805.01 KB total size

0 open issues

0 open pull requests

0 watchers

0 forks

0 stars

46 views

Updated Jan 20, 2026

Recent Commits View all

Initial commit - Upload project 'blender-mcp'

WebDev committed Jan 20, 2026

Languages

Python 98.9%

LICENSE 0.6%

TOML 0.5%