README.md
Enables Claude AI to directly control Blender for automated 3D modeling
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.
Join the Community
Give feedback, get inspired, and build on top of the MCP: Discord
Supporters
All supporters:
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
- First-class tools: Common Blender operations are exposed as typed MCP tools (not just Python execution)
- DSL allowlist: Execute a validated list of allowlisted operations via
execute_ops(safer than arbitrary Python) - Object manipulation: Create, modify, and delete 3D objects in Blender
- Material control: Create/assign materials, set PBR params, and wire texture maps
- 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:
- 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
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 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")
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)BLENDER_AUTH_TOKEN: Optional shared secret. If set in Blender (Addon Preferences) the MCP server must send the same token.BLENDER_MCP_TOOL_PROFILE: Controls how many MCP tools are exposed (default:"standard").
Tool profiles:
minimal: Exposes onlyget_scene_info,get_viewport_screenshot,get_capabilities,execute_opsstandard(default):minimal+ common wrappers (create_primitive,set_transform,select_objects,assign_material,render_still)- Integration tools (PolyHaven/Sketchfab/Hyper3D/Hunyuan) are only registered if the Blender add-on reports them enabled at server startup (restart required to re-evaluate).
full: Exposes all tools (including advanced wrappers and theexecute_blender_codeescape hatch)
Example:
export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876
export BLENDER_AUTH_TOKEN='...'
export BLENDER_MCP_TOOL_PROFILE='standard'
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
](Tools (10)
get_scene_infoGet detailed information about the current Blender scene.get_viewport_screenshotView screenshots for Blender viewport to better understand the scene.get_capabilitiesCheck available features and integrations enabled in the Blender addon.execute_opsExecute a validated list of allowlisted operations via DSL.create_primitiveCreate 3D objects like cubes, spheres, or planes in the scene.set_transformModify the location, rotation, or scale of selected objects.select_objectsSelect specific objects in the Blender scene.assign_materialCreate or assign materials and set PBR parameters.render_stillRender the current scene to a still image.execute_blender_codeRun arbitrary Python code directly within Blender.Environment Variables
BLENDER_HOSTHost address for Blender socket server (default: "localhost")BLENDER_PORTPort number for Blender socket server (default: 9876)BLENDER_AUTH_TOKENOptional shared secret for authenticationBLENDER_MCP_TOOL_PROFILEControls how many MCP tools are exposed (minimal, standard, full)Configuration
claude_desktop_config.json
{
"mcpServers": {
"blender": {
"command": "uvx",
"args": [
"blender-mcp"
]
}
}
}Try it
→Create a 3D scene with a red cube and a blue sphere on a wooden floor.
→Take a screenshot of the current Blender viewport so I can see the layout.
→Search Sketchfab for a low-poly tree model and import it into my scene.
→Apply a metallic PBR material to the selected object.
→Run a Python script in Blender to randomize the location of all selected objects.