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

Give feedback, get inspired, and build on top of the MCP: Discord

CodeRabbit

Satish Goda

All supporters:

Support this project

• Added Hunyuan3D support

• 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)

• 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!

• Two-way communication: Connect Claude AI to Blender through a socket-based server
• Object manipulation: Create, modify, and delete 3D objects in Blender
• Scene inspection: Get detailed information about the current Blender scene
• Code execution: Run arbitrary Python code in Blender from Claude

BlenderMCP includes three powerful enhancement systems to transform basic 3D models into production-quality renders:

Transform flat materials into realistic PBR shaders

• 20+ material presets (metals, glass, paint, wood, plastics, stone)
• Procedural texture generation (scratches, dirt, wood grain, etc.)
• Smart auto-enhancement based on object names
• See MATERIAL_SYSTEM.md for details

Enhance geometry quality of low-poly AI-generated models

• 5 enhancement presets (smooth, high_detail, mechanical, organic, architectural)
• Automatic subdivision surface (16-256x geometry increase)
• Edge beveling for realistic edges
• Mesh analysis and recommendations
• See POST_PROCESSING.md for details

Professional cinematic lighting and rendering

• HDRI environment lighting (6 presets)
• Multi-light rigs (5 configurations)
• Volumetric atmosphere (fog, god rays, haze)
• Camera setup with DOF
• Render quality presets
• Auto-setup based on scene description
• See LIGHTING_SYSTEM.md for details

Character animation for third-person games

• 14 animation presets (idle, walk, run, jump, aim, recoil, death, etc.)
• Support for Mixamo, Rigify, and generic bone rigs
• Keyframe insertion with 13 interpolation types
• NLA track support for animation layering
• FBX export for Unity, Unreal, and Godot
• AI-powered animation preset suggestions
• See ANIMATION_SYSTEM.md for details

Quick Animation Example:

# Apply preset animation to character
await apply_animation_preset(ctx, "idle", "Armature")

# Or create custom animation
await insert_keyframe(ctx, "Armature", "mixamorig:Head", 1, rotation=[0, 0, 0])
await insert_keyframe(ctx, "Armature", "mixamorig:Head", 30, rotation=[15, 0, 0])

# Export for game engine
await export_animation_fbx(ctx, "/path/to/anim.fbx", "Armature")

Quick Enhancement Example:

# Import AI-generated model
import_generated_asset(name="booth", task_uuid="...")

# Transform with one command each
auto_enhance_geometry("booth")           # Smooth geometry
auto_enhance_materials("booth", True)    # Add realistic materials  
auto_setup_scene_lighting("dramatic outdoor", "booth")  # Professional lighting

# Result: Production-quality render in seconds

See QUICK_REFERENCE.md for complete enhancement workflows.

• Hyper3D Rodin: Generate 3D models from text or images
• Hunyuan3D: Alternative 3D model generation
• Smart enhancement: Automatically improve AI-generated models

• PolyHaven: Search and download HDRIs, textures, and models
• Sketchfab: Search and download 3D models
• Material control: Apply and modify materials and colors

Export your work to various formats and share materials between projects

• Object Export: Export meshes to FBX, OBJ, GLB, GLTF, STL, PLY, DAE formats
• Material Export: Save materials as JSON or Blender library files
• Material Import: Import materials from JSON or BLEND files
• Material Management: List, inspect, and share material data
• See EXPORT_FEATURES.md for complete documentation

Quick Export Example:

# Export model for Unity/Unreal
export_object(
    object_names=["Character"],
    filepath="/game/assets/character.fbx",
    export_format="FBX",
    include_materials=True
)

# Share material between projects
export_material(
    material_name="MyMaterial",
    filepath="/shared/materials/awesome.json",
    pack_textures=True
)

The system consists of two main components:

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

The easiest way to run BlenderMCP is using Docker, which handles all dependencies automatically.

• Docker and Docker Compose installed
• Blender 3.0 or newer running on your host machine (tested up to Blender 5.0)

1. Clone or download this repository
2. Install the Blender addon (see Installing the Blender Addon section below)
3. Start Blender and enable the BlenderMCP addon
4. Build and run the Docker container:

# Build and start the container
docker-compose up --build

# Or run in detached mode
docker-compose up --build -d

The Docker container will automatically connect to Blender running on your host machine using host.docker.internal:9876.

You can customize the connection by setting environment variables in the docker-compose.yml file:

• BLENDER_HOST: Host address for Blender socket server (default: "host.docker.internal")
• BLENDER_PORT: Port number for Blender socket server (default: 9876)

• Blender 3.0 or newer (tested up to Blender 5.0)
• 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

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

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"
            ]
        }
    }
}

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

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

1. Download the addon.py file from this repo
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"

1. Make sure Blender is running with the BlenderMCP addon enabled
2. Start the Docker container:

   docker-compose up --build

3. Configure Claude Desktop or Cursor with the MCP server (see integration sections above)
4. The Docker container will handle the MCP server connection to Blender

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 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 through Poly Haven
• AI generated 3D models through Hyper3D Rodin

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'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.

• 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

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

⚠️ CRITICAL SECURITY WARNING: The execute_blender_code tool executes arbitrary Python code in Blender with full API access. This is powerful but potentially dangerous:

• Only use with trusted prompts and commands
• Code can access your file system, modify Blender data, and execute system commands
• ALWAYS save your work before using this feature
• Consider disabling this feature in multi-user or untrusted environments
• Review generated code before execution when possible

🔐 Protecting Your API Keys:

1. Never commit API keys to version control
2. API keys entered in the Blender addon UI are stored in Blender's scene properties and may be saved in .blend files
3. Be careful sharing .blend files that contain API keys
4. Rotate keys regularly
5. Use different keys for development and production
6. The free trial key for Hyper3D has been removed from the codebase for security - get your own key from hyper3d.ai or fal.ai

📊 Anonymous Telemetry: This project collects anonymous usage data to help improve the tool:

• What is collected: Tool execution events, error messages, platform info, anonymous customer UUID
• What is NOT collected: Prompt text (unless explicitly enabled), personal information, file paths
• Completely anonymous: No way to identify individual users

To disable telemetry, set any of these environment variables:

# Any of these will disable telemetry
export DISABLE_TELEMETRY=true
export BLENDER_MCP_DISABLE_TELEMETRY=true
export MCP_DISABLE_TELEMETRY=true

Or add to your shell profile (~/.zshrc, ~/.bashrc, etc.):

echo 'export DISABLE_TELEMETRY=true' >> ~/.zshrc

For Docker users, add to your docker-compose.yml:

environment:
  - DISABLE_TELEMETRY=true

🔒 Socket Server: The Blender addon creates a TCP socket server on port 9876:

• Binds to localhost only - not accessible from other machines by default
• No authentication - any local process can connect
• Recommended for development/personal use only
• For production use, consider implementing authentication or running in an isolated environment

See .env.example for all available configuration options.

• Complex operations might need to be broken down into smaller steps
• 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
• Network connection required for external asset downloads and AI generation features

Contributions are welcome! Please feel free to submit a Pull Request.

This is a third-party integration and not made by Blender. Made by Siddharth