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.

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

Satish Goda

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
🆕 Retopology Tools: Professional retopology workflow with mesh analysis, remeshing, and optimization

🆕 Retopology Features

BlenderMCP now includes a comprehensive suite of retopology tools for creating game-ready, optimized meshes:

Mesh Analysis

mesh_stats - Get detailed topology metrics (verts/edges/faces, tri/quad/ngon counts, surface area, volume)
detect_topology_issues - Identify non-manifold edges, loose geometry, inverted normals, and duplicates

Remeshing Operations

voxel_remesh - Rebuild meshes with uniform voxel-based topology
quadriflow_remesh - Generate quad-dominant meshes (best for animation/subdivision)
decimate - Reduce polygon count while preserving shape (great for LODs)
shrinkwrap_reproject - Project low-poly meshes onto high-poly surfaces

Viewport & Shading

set_view_projection - Toggle between orthographic and perspective view
align_view_to_axis - Snap view to Front/Back/Left/Right/Top/Bottom
frame_selected - Frame selected objects in viewport
mark_seams_by_angle - Auto-mark UV seams based on edge angles
mark_sharp_by_angle - Mark sharp edges for proper shading

Guided Workflow

Retopo Pipeline Prompt - Step-by-step guidance for complete retopology workflows

For detailed retopology workflows, see the Retopology Guide below.

Components

The system consists of two main components:

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

🏗️ Modular Architecture

BlenderMCP follows a clean modular architecture:

src/
├── server.py          # MCP server (import & wrappers only)
├── tools/             # Tool implementations
│   ├── mesh_analysis.py
│   ├── remeshing.py
│   ├── viewport.py
│   ├── shading.py
│   ├── scene.py
│   └── integrations/  # External services
│       ├── polyhaven.py
│       ├── sketchfab.py
│       └── hyper3d.py
└── prompts/           # Guided workflows
    ├── retopo.py
    └── asset_creation.py

For developers: See Architecture Guide and Refactoring Summary for details on code organization and how to add new tools.

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

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:

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:

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

Visual Studio Code Integration

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

Installing the Blender Addon

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

Usage

Starting the Connection

BlenderMCP in the sidebar

In Blender, go to the 3D View sidebar (press N if not visible)
Find the "BlenderMCP" tab
Turn on the Poly Haven checkbox if you want assets from their API (optional)
Click "Connect to Claude"
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.

API Keys and External Services

BlenderMCP integrates with several external services to provide enhanced functionality. Understanding how API keys work is important for production use.

Shared Trial Keys

Important: The Blender addon (addon.py) includes a shared free trial key for Hyper3D Rodin API:

Location: addon.py line 31 (RODIN_FREE_TRIAL_KEY)
Purpose: Allows users to test 3D model generation without setup
Limitations: Shared among all users, daily generation limits apply

Warning: This shared key is intended for testing and development only. For production use or heavier usage, you should obtain your own API keys.

Obtaining Your Own API Keys

For production use or if you exceed the free trial limits, obtain personal API keys from:

Hyper3D Rodin (AI-generated 3D models)
- Website: hyper3d.ai
- Also requires: fal.ai account
- Purpose: Generate 3D models from text descriptions
- Replace the key in addon.py or configure via environment variable
Poly Haven (Free 3D assets)
- Website: polyhaven.com
- No API key required (free public API)
- Purpose: Download HDRIs, textures, and 3D models
- Enable via checkbox in Blender addon UI
Sketchfab (3D model marketplace)
- Website: sketchfab.com
- Purpose: Search and download 3D models
- API access: May require account for full functionality

Security Best Practices

Never commit personal API keys to version control
Use environment variables for production deployments
Rotate keys regularly if they are exposed
Monitor usage to detect unauthorized access
Keep trial keys separate from production keys

For Developers

If you're extending BlenderMCP with additional external service integrations:

Store API keys in environment variables, not hardcoded in source
Document required API keys in the README
Provide clear instructions for users to obtain their own keys
Consider implementing rate limiting and error handling for API calls

Retopology Guide

BlenderMCP includes a comprehensive retopology toolkit for creating game-ready, optimized meshes from high-poly sources.

For detailed workflows, tool references, and best practices, please see the Retopology Guide.

Quick Start

The easiest way to start is to use the Retopo Pipeline prompt:

Use the "retopo_pipeline" prompt to guide me through retopologizing this mesh

BDD Test Specifications

All retopology features are documented with Behavior-Driven Development (BDD) specifications in the features/ directory:

01_mcp_contract.feature - MCP tools/resources/prompts discovery
02_mesh_analysis.feature - Topology metrics and issue detection
03_voxel_remesh.feature - Voxel-based remeshing
04_quadriflow_remesh.feature - Quad-dominant remeshing
05_decimation.feature - Polygon reduction
06_shrinkwrap.feature - Surface projection
07_seams_shading.feature - UV seams and sharp edge marking
08_viewport_controls.feature - View projection and alignment

These feature files serve as both specification and documentation for the retopology system.

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

Testing

BlenderMCP includes a comprehensive test suite, including Real Integration Tests that run against a headless Blender instance.

See tests/README.md for detailed instructions on running tests.

Quick Start for Tests

# Run all tests (including mocked unit tests)
pytest tests/

# Run real integration tests (requires local Blender installation)
pytest tests/integration/ -v

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