Blender MCP server

BlenderMCP connects Blender to Claude AI through the Model Context Protocol (MCP), allowing AI-assisted 3D modeling, scene creation, and manipulation. This integration enables Claude to directly interact with and control Blender, creating a powerful workflow for AI-driven 3D content creation.

Installation

Prerequisites

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

Install uv based on your operating system:

Mac:

brew install uv

Windows:

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

For other systems, follow the installation instructions at Install uv.

Claude for Desktop Integration

Configure Claude to recognize the Blender MCP server:

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

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

Cursor Integration

Mac users:

1. Go to Settings > MCP
2. Use "add new global MCP server" button or create .cursor/mcp.json in your project root
3. Paste the following configuration:

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

Windows users:

1. Go to Settings > MCP > Add Server
2. Add a new server with these settings:

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

⚠️ Important: 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 the repository
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, open the 3D View sidebar (press N if not visible)
2. Find the "BlenderMCP" tab
3. Enable the Poly Haven checkbox if you want to use assets from their API (optional)
4. Click "Connect to Claude"
5. Make sure the MCP server is running in your terminal

Working with Claude

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

Capabilities

BlenderMCP enables 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
• View screenshots of the Blender viewport
• Search and download Sketchfab models

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 you to generate a limited number of models per day. If you reach the daily limit, you can:

• Wait for the next day's reset
• 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 manually run the uvx command in the terminal.
• Timeout errors: Try simplifying your requests or breaking them into smaller steps.
• Poly Haven integration: Be aware that Claude may show inconsistent behavior with this feature.
• Restart if necessary: If connection errors persist, try restarting both Claude and the Blender server.

Technical Details

Communication Protocol

The system uses a 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 and always save your work before using it.
• Poly Haven requires downloading models, textures, and HDRI images. If you don't want to use this feature, disable it using the checkbox in Blender.
• Complex operations might need to be broken down into smaller steps.

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