BlenderMCP
About
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.
Details
- Repository
- ahujasid/blender-mcp
- License
- MIT
Explore
| | |
|---|---|
| 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 |
| Asset & model generation | Poly Haven assets, Sketchfab models, and AI-generated 3D models via Hyper3D Rodin and Hunyuan3D |
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
BlenderMCPCommand (node, npx, python, etc.)uvxArguments-
Argument 1
blender-mcp
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
-
Argument 1
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Three steps: install uv, point your MCP client at the server, install the Blender addon.
1. Install uv
On locked-down machines you can skip uvx entirely with pipx, then point your client at the installed command:
pipx install blender-mcp
pipx ensurepath # then restart your shell / client
``
Use the resulting absolute path as
"command" (find it with which blender-mcp / where blender-mcp) and omit args.
The following environment variables can be used to configure the Blender connection:
| Variable | Default | Description |
|---|---|---|
|
BLENDER_HOST | localhost | Host address for Blender socket server |
| BLENDER_PORT | 9876` | Port number for Blender socket server |get_scene_info
Get detailed information about the current Blender scene
get_object_info
Get detailed information about a specific object in the Blender scene. Parameters: - object_name: The name of the object to get information about
get_viewport_screenshot
Capture a screenshot of the current Blender 3D viewport. Parameters: - max_size: Maximum size in pixels for the largest dimension (default: 800) Returns the screenshot as an Image.
execute_blender_code
Execute arbitrary Python code in Blender. Make sure to do it step-by-step by breaking it into smaller chunks. Parameters: - code: The Python code to execute
get_polyhaven_categories
Get a list of categories for a specific asset type on Polyhaven. Parameters: - asset_type: The type of asset to get categories for (hdris, textures, models, all)
search_polyhaven_assets
Search for assets on Polyhaven with optional filtering. Parameters: - asset_type: Type of assets to search for (hdris, textures, models, all) - categories: Optional comma-separated list of categories to filter by Returns a list of matching assets with basic information.
download_polyhaven_asset
Download and import a Polyhaven asset into Blender. Parameters: - asset_id: The ID of the asset to download - asset_type: The type of asset (hdris, textures, models) - resolution: The resolution to download (e.g., 1k, 2k, 4k) - file_format: Optional file format (e.g., hdr, exr for HDRIs; jpg, png for textures; gltf, fbx for models) Returns a message indicating success or failure.
set_texture
Apply a previously downloaded Polyhaven texture to an object. Parameters: - object_name: Name of the object to apply the texture to - texture_id: ID of the Polyhaven texture to apply (must be downloaded first) Returns a message indicating success or failure.
get_polyhaven_status
Check if PolyHaven integration is enabled in Blender. Returns a message indicating whether PolyHaven features are available.
get_hyper3d_status
Check if Hyper3D Rodin integration is enabled in Blender. Returns a message indicating whether Hyper3D Rodin features are available. Don't emphasize the key type in the returned message, but sliently remember it.
get_sketchfab_status
Check if Sketchfab integration is enabled in Blender. Returns a message indicating whether Sketchfab features are available.
search_sketchfab_models
Search for models on Sketchfab with optional filtering. Parameters: - query: Text to search for - categories: Optional comma-separated list of categories - count: Maximum number of results to return (default 20) - downloadable: Whether to include only downloadable models (default True) Returns a formatted list of matching models.
download_sketchfab_model
Download and import a Sketchfab model by its UID. Parameters: - uid: The unique identifier of the Sketchfab model Returns a message indicating success or failure. The model must be downloadable and you must have proper access rights.
generate_hyper3d_model_via_text
Generate 3D asset using Hyper3D by giving description of the desired asset, and import the asset into Blender. The 3D asset has built-in materials. The generated model has a normalized size, so re-scaling after generation can be useful. Parameters: - text_prompt: A short description of the desired model in **English**. - bbox_condition: Optional. If given, it has to be a list of floats of length 3. Controls the ratio between [Length, Width, Height] of the model. Returns a message indicating success or failure.
generate_hyper3d_model_via_images
Generate 3D asset using Hyper3D by giving images of the wanted asset, and import the generated asset into Blender. The 3D asset has built-in materials. The generated model has a normalized size, so re-scaling after generation can be useful. Parameters: - input_image_paths: The **absolute** paths of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in MAIN_SITE mode. - input_image_urls: The URLs of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in FAL_AI mode. - bbox_condition: Optional. If given, it has to be a list of ints of length 3. Controls the ratio between [Length, Width, Height] of the model. Only one of {input_image_paths, input_image_urls} should be given at a time, depending on the Hyper3D Rodin's current mode. Returns a message indicating success or failure.
poll_rodin_job_status
Check if the Hyper3D Rodin generation task is completed. For Hyper3D Rodin mode MAIN_SITE: Parameters: - subscription_key: The subscription_key given in the generate model step. Returns a list of status. The task is done if all status are "Done". If "Failed" showed up, the generating process failed. This is a polling API, so only proceed if the status are finally determined ("Done" or "Canceled"). For Hyper3D Rodin mode FAL_AI: Parameters: - request_id: The request_id given in the generate model step. Returns the generation task status. The task is done if status is "COMPLETED". The task is in progress if status is "IN_PROGRESS". If status other than "COMPLETED", "IN_PROGRESS", "IN_QUEUE" showed up, the generating process might be failed. This is a polling API, so only proceed if the status are finally determined ("COMPLETED" or some failed state).
import_generated_asset
Import the asset generated by Hyper3D Rodin after the generation task is completed. Parameters: - name: The name of the object in scene - task_uuid: For Hyper3D Rodin mode MAIN_SITE: The task_uuid given in the generate model step. - request_id: For Hyper3D Rodin mode FAL_AI: The request_id given in the generate model step. Only give one of {task_uuid, request_id} based on the Hyper3D Rodin Mode! Return if the asset has been imported successfully.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"blendermcp": {
"env": {},
"args": [
"blender-mcp"
],
"command": "uvx"
}
}
}Linux
{
"env": [],
"args": [
"blender-mcp"
],
"command": "uvx"
}Macos
{
"env": [],
"args": [
"blender-mcp"
],
"command": "uvx"
}Windows
{
"env": [],
"args": [
"/c",
"uvx",
"blender-mcp"
],
"command": "cmd"
}Prompt-assisted 3D modeling, scene creation, and manipulation — driven by AI.
Website·Full Tutorial·Discord·Releases·Sponsor
Three steps: installuv, point your MCP client at the server, install the Blender addon.
# macOS brew install uv # Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Warning:Do not proceed before installing uv. Use the official installer —notpip install uv.
{ "mcpServers": { "blender": { "command": "uvx", "args": ["blender-mcp"] } } }
SeeMCP Client Setupbelow for per-client instructions and one-click install buttons.
Then in Blender:Edit → Preferences → Add-ons→ enableInterface: Blender MCP.
In Blender's 3D viewport, pressN→ open theBlenderMCPtab → clickStart MCP Server. That's it — ask Claude to build something.
Note:Only runoneinstance of the MCP server (either Cursor or Claude Desktop), not both.
- Quickstart
- Features
- Components
- Installation
- Prerequisites
- Make your client find uvx
- Pin the Python version
- Install without uv
- Environment Variables
- Claude for Desktop
- Cursor
- Visual Studio Code
- OpenCode
- Starting the Connection
- Using with Claude
- Capabilities
- Example Commands
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/blender_mcp/server.py) — a Python server that implements the Model Context Protocol and connects to the Blender addon
- Blender3.0 or newer
- Python3.10 or newer
- uvpackage manager
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Then add uv to the user path in Windows (you may need to restart Claude Desktop after):
$localBin = "$env:USERPROFILE\.local\bin" $userPath = [Environment]::GetEnvironmentVariable("Path", "User") [Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User")
curl -LsSf https://astral.sh/uv/install.sh | sh
It lands in~/.local/bin— open a new shell so it's on your PATH.
Otherwise, installation instructions are on their website:Install uv
On every OS, use uv'sofficial installer above — notpip install uv, which may not create theuvxcommand and can hide uv inside an environment your client can't see.
Warning:Do not proceed before installing uv.
MCP clients started from a GUI (Claude Desktop, Cursor, VS Code from the Dock/Start menu) donotinherit your terminal's PATH, so a bare"command": "uvx"can fail withspawn uvx ENOENTeven thoughuvxworks in your terminal. If that happens:
- Find uvx's full path —which uvx(macOS/Linux) orwhere uvx(Windows) — and use it as"command", e.g./opt/homebrew/bin/uvxorC:\Users\<you>\.local\bin\uvx.exe.
- On Windows you can instead wrap it:"command": "cmd", "args": ["/c", "uvx", "blender-mcp"].
- After any PATH or config change,fully quit and relaunchthe client (Windows: quit from the system tray, not just the window; macOS:Cmd+Q).
Avoid conda / pyenv / version conflicts.
uv chooses which Python runs the server. On machines with conda (auto-activated base), pyenv, or asdf — or with a newer CPython release that some dependencies do not have wheels for yet — uv can grab an interpreter that makes installation fail. Pin Python 3.11 and prefer uv-managed interpreters to avoid using whatever is on your PATH:
{ "mcpServers": { "blender": { "command": "uvx", "args": ["--python", "3.11", "blender-mcp"], "env": { "UV_PYTHON_PREFERENCE": "only-managed" } } } }
--python 3.11still satisfies this package'srequires-python >=3.10, andUV_PYTHON_PREFERENCE=only-managedkeeps uv from selecting conda, pyenv, asdf, or system Python first. (The repo's.python-versionis only a hint for contributors and doesnotaffectuvx.)
If a previous failed attempt keeps replaying after a fix, clear the cache:
uv cache clean blender-mcp && uvx --refresh blender-mcp
On locked-down machines you can skip uvx entirely withpipx, then point your client at the installed command:
pipx install blender-mcp pipx ensurepath # then restart your shell / client
Use the resulting absolute path as"command"(find it withwhich blender-mcp/where blender-mcp) and omitargs.
The following environment variables can be used to configure the Blender connection:
export BLENDER_HOST='host.docker.internal' export BLENDER_PORT=9876
Watch the setup instruction video(assuming you have already installed uv)
Go toClaude → Settings → Developer → Edit Config →claude_desktop_config.jsonand include the following:
{ "mcpServers": { "blender": { "command": "uvx", "args": [ "blender-mcp" ] } } }
Use the Claude Code CLI to add the blender MCP server:
macOS— go toSettings → MCPand paste the following:
- To use as a global server, use the"add new global MCP server"button and paste
- To use as a project-specific server, create.cursor/mcp.jsonin the root of the project and paste
{ "mcpServers": { "blender": { "command": "uvx", "args": [ "blender-mcp" ] } } }
Windows— go toSettings → MCP → Add Server, add a new server with the following settings:
{ "mcpServers": { "blender": { "command": "cmd", "args": [ "/c", "uvx", "blender-mcp" ] } } }
Note:Only runoneinstance of the MCP server (either on Cursor or Claude Desktop), not both.
Prerequisites: Make sure you haveVisual Studio Codeinstalled before proceeding.
{ "mcp": { "blender-mcp": { "type": "local", "command": ["uvx", "blender-mcp"], "enabled": true, "environment": { "BLENDER_HOST": "localhost", "BLENDER_PORT": "9876" } } } }
This copies the addon into your Blender addons folder asblender_mcp.py. It prints where it wrote to, and keeps a.bakof any file it replaces.
Optional:uvx blender-mcp addon-pathslists detected Blender addons folders. Override the destination withBLENDERMCP_ADDONS_DIR=/path/to/scripts/addons.
4.EnableInterface: Blender MCP(search "Blender MCP"). If it doesn't appear yet, clickInstall…and select the copiedblender_mcp.py/addon.py, or restart Blender.
5. Manual alternative— if the command above can't find your Blender install, or you prefer doing it by hand: downloadaddon.pyfrom this repo → in Blender,Edit → Preferences → Add-ons → Install…→ select the downloadedaddon.py→ enable it.
Then open theBlenderMCPtab in Blender's sidebar (pressNin the 3D viewport) and clickStart MCP Server. SeeStarting the Connectionbelow.
For newcomers, go straight toQuickstart. For existing users, see below.
uvx blender-mcp install-addon uvx blender-mcp addon-paths # optional: list detected Blender addons folders
2.In Blender:Preferences → Add-ons→ disable and re-enableInterface: Blender MCP(or restart Blender), then clickStart MCP Serveragain.
3.Delete the MCP server from Claude and add it back again if the server package itself needs a refresh.
Note:the MCP server never modifies your Blender addon files on its own. When it starts, it checks whether the installed addon is behind the bundled copy and logs how to update;install-addonis what actually writes, and it keeps a.bakof the file it replaces. Trajectory capture still works on older loaded addons via anexecute_codefallback.
- In Blender, go to the 3D View sidebar (pressNif not visible)
- Find theBlenderMCPtab
- Turn on the checkboxes you'd like to use (see more underCapabilitiesbelow)
- ClickConnect to Claude
- Make sure the MCP server is running in your terminal
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.
- 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 throughPoly Haven
- Search and download models fromSketchfab
- AI generated 3D models throughHyper3D RodinandHunyuan3D
Here are some examples of what you can ask Claude to do:
BlenderMCP supports persistent credentials via Blender Add-on Preferences:
Edit → Preferences → Add-ons → Blender MCP
You can store these values there so they survive Blender restarts:
- Sketchfab API Key
- Hyper3D API Key
- Hunyuan3D SecretId / SecretKey
- Hunyuan3D API URL
For headless setups or CI, credentials can also be injected by environment variables:
The system uses a simple JSON-based protocol over TCP sockets:
- Commandsare sent as JSON objects with atypeand optionalparams
- Responsesare JSON objects with astatusandresultormessage
Limitations & Security Considerations
Warning:Theexecute_blender_codetool 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.
BlenderMCP collects anonymous usage data to help improve the tool. Telemetry consent ison by default, and you can turn it off in two ways:
1. In Blender— go toEdit → Preferences → Add-ons → Blender MCPand uncheck the telemetry consent checkbox.
- With consent (checked, the default): view the TnC for more details on data collected.
2. Environment Variable— completely disable all telemetry by running:
{ "mcpServers": { "blender": { "command": "uvx", "args": ["blender-mcp"], "env": { "DISABLE_TELEMETRY": "true" } } } }
Telemetry data is not linked to your name or account. It may be used to improve BlenderMCP, for research, and to train AI models.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
