Blender MCP server

Enables natural language control of Blender for 3D scene creation, manipulation, and rendering without requiring knowledge of Blender's interface or Python API.
Back to servers
Setup instructions
Provider
Siddharth Ahuja
Release date
Mar 07, 2025
Language
Python
Stats
13.2K stars

BlenderMCP connects Blender to Claude AI through the Model Context Protocol (MCP), enabling AI-assisted 3D modeling and scene creation. This integration allows Claude to directly interact with and control Blender through a socket-based server, making it possible to create and manipulate 3D objects via natural language prompts.

Prerequisites

Before installing BlenderMCP, ensure you have:

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

Installing uv

On Mac:

brew install uv

On Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
set Path=C:\Users\nntra\.local\bin;%Path%

For other platforms, installation instructions are available at UV installation guide.

Installation

Setting Up the Blender Addon

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

Configuring Claude for Desktop

  1. Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json
  2. Add the following configuration:
{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": [
                "blender-mcp"
            ]
        }
    }
}

Watch the setup instruction video: Claude Desktop Setup

Cursor Integration

For Mac users: Go to Settings > MCP and add either:

  • A global server using "add new global MCP server" button
  • A project-specific server by creating .cursor/mcp.json in the project root

Use this configuration:

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

For Windows users: Go to Settings > MCP > Add Server, and add a new server with:

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

Setup video: Cursor setup

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

Visual Studio Code Integration

Make sure you have Visual Studio Code installed before proceeding, then use the integration button provided in the repository.

Environment Variables (Optional)

You can configure the Blender connection using these environment variables:

  • BLENDER_HOST: Host address for Blender socket server (default: "localhost")
  • BLENDER_PORT: Port number for Blender socket server (default: 9876)

Example:

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

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

Once connected, you'll see a hammer icon in Claude with tools for the Blender MCP.

Capabilities

BlenderMCP allows Claude to:

  • Get scene and object information
  • Create, delete and modify 3D shapes
  • Apply or create materials for objects
  • Execute Python code in Blender
  • Download models, assets and HDRIs through Poly Haven
  • Generate 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"
  • "Create a beach vibe using HDRIs, textures, and models like rocks and vegetation from Poly Haven"
  • "Generate a 3D model of a garden gnome through Hyper3D"
  • "Get information about the current scene, and make a threejs sketch from it"
  • "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 a limited number of model generations per day. If you reach the daily limit, you can wait for the next day's reset or obtain your own key from hyper3d.ai and fal.ai.

Troubleshooting

  • Connection issues: Ensure the Blender addon server is running and the MCP server is configured on Claude. Don't run the uvx command in the terminal manually.
  • Timeout errors: Try simplifying your requests or breaking them into smaller steps.
  • Poly Haven integration: Claude's behavior with Poly Haven can sometimes be erratic.
  • Restart both applications: If you continue to have connection errors, try restarting both Claude and the Blender server.

Remember to always save your work before using the execute_blender_code tool, as it can run arbitrary Python code in Blender.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "blender" '{"command":"uvx","args":["blender-mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later