Skip to main content
Glama
BlenderMCP

BlenderMCP

by KorwinTeo

BlenderMCP connects Blender 3D to Claude AI (and any other LLM) through the Model Context Protocol. It enables prompt-driven 3D modeling, scene creation, and real-time object manipulation β€” directly from your AI assistant.


Table of Contents


Related MCP server: BlenderMCP

Features

Capability

Description

πŸ”

Two-way communication

Real-time socket bridge between Claude and Blender

🧊

Object manipulation

Create, move, scale, and delete 3D objects via prompts

🎨

Material control

Apply, modify, and generate materials and colors

πŸ”

Scene inspection

Full scene state β€” objects, lights, cameras

πŸ“·

Viewport screenshot

Let the AI see the Blender viewport

🐍

Code execution

Run arbitrary Python inside Blender

🌍

Poly Haven

Download HDRIs, textures, and models via API

πŸ€–

AI model generation

3D assets via Hyper3D Rodin and Hunyuan3D

πŸ—‚οΈ

Sketchfab

Search and import 3D models

🌐

Remote host

Run the MCP server on a remote machine


Whats New

Full changelog: Releases

  • Hunyuan3D 3D model generation

  • Viewport screenshot for scene understanding

  • Sketchfab model search and import

  • Poly Haven asset integration

  • Hyper3D Rodin AI model generation

  • Remote host support

Updating from an older version:

  1. Download the latest addon.py and replace it in Blender

  2. Remove and re-add the MCP server in your client config

Codex

Add to ~/.codex/config.toml (or %USERPROFILE%\.codex\config.toml on Windows):

[mcp_servers.blender]
command = "uvx"
args = ["blender-mcp"]

On Windows, if uvx is missing from PATH, set command to the full uvx.exe path.

Hunyuan3D

Mode

What you need

official api

Tencent Cloud SecretId + SecretKey (billed per job)

local api (default)

Your own Hunyuan3D inference server β€” BlenderMCP only POSTs to {API URL}/generate and imports the GLB. Default URL is http://localhost:8081. Nothing is bundled or started for you.

Remote Blender host

  1. In the BlenderMCP panel, enable Listen on all interfaces (0.0.0.0) only on a trusted network (no auth on the socket).

  2. Point the MCP client at Blender with BLENDER_HOST / BLENDER_PORT.


Quick Start

# macOS
brew install uv

Add to Claude > Settings > Developer > Edit Config > claude_desktop_config.json:

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

Install the Blender addon, click Connect, and start prompting.


Installation

Prerequisites

Requirement

Minimum version

Blender

3.0

Python

3.10

uv

Latest

Install uv:

brew install uv
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Add to PATH (restart your client 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

Do not use pip install uv β€” it may not create the uvx command.


uvx not found by your client

GUI clients don't inherit your terminal PATH. Get the full path:

  • which uvx (macOS/Linux) or where uvx (Windows)

  • Use it as "command" in your config

  • Windows: "command": "cmd", "args": ["/c", "uvx", "blender-mcp"]

  • Fully quit and relaunch your client after any config change

Apple Silicon (M1/M2/M3/M4) arch mismatch

If uvx tries to build for x86_64 on an arm64 Mac (cryptography wheel errors), force arm64 Python:

"args": ["--python", "3.11-aarch64", "blender-mcp"]

Docker / WSL / remote host

Blender must listen where the MCP process can reach it:

"env": {
  "BLENDER_HOST": "host.docker.internal",
  "BLENDER_PORT": "9876"
}

On WSL2 talking to Windows Blender, try BLENDER_HOST=127.0.0.1 or your Windows host IP. Screenshots are returned as base64 (no shared temp path required).

Blender versions

Blender 3.0+ is supported; 4.x / 5.x recommended. Use a normal GUI Blender session (not blender -b background) so the MCP socket and viewport tools work.

Keep addon and server in sync

The TCP link uses length-prefixed JSON frames. Update both the Blender addon (addon.py) and the MCP package (uvx --refresh blender-mcp) together after upgrades.

Windows: Claude Extension egg_base '.' does not exist

If Claude Desktop’s built-in extension fails to build with egg_base / wrong path under Packages\Claude_..., skip the extension launcher and run the package via uvx (config above). That path is the supported install on Windows.

uv tool install blender-mcp
uv tool upgrade blender-mcp
uvx --refresh blender-mcp

blender-mcp does not depend on pywin32. If uv tries to install a locked pywin32 wheel from an old env, clear the stuck build cache or use a fresh uvx/uv tool install rather than a partial site-packages tree.


Claude Desktop

Watch setup video

Claude > Settings > Developer > Edit Config > claude_desktop_config.json:

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["blender-mcp"]
        }
    }
}
{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["--python", "3.11", "blender-mcp"],
            "env": { "UV_PYTHON_PREFERENCE": "only-managed" }
        }
    }
}
pipx install blender-mcp
pipx ensurepath

Cursor

Install MCP Server

Watch Cursor setup video

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

Run only one MCP server at a time β€” Cursor or Claude Desktop, not both.


VS Code

Install in VS Code

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

OpenCode

{
  "mcp": {
    "blender-mcp": {
      "type": "local",
      "command": ["uvx", "blender-mcp"],
      "enabled": true,
      "environment": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }
    }
  }
}

Claude Code CLI

claude mcp add blender uvx blender-mcp

Blender Addon

  1. Download addon.py

  2. In Blender: Edit > Preferences > Add-ons > Install...

  3. Select addon.py

  4. Enable "Interface: Blender MCP"


Usage

Starting the Connection

BlenderMCP sidebar

  1. Open the 3D View sidebar (press N if not visible)

  2. Go to the BlenderMCP tab

  3. (Optional) Enable Poly Haven for asset downloads

  4. Click Connect to Claude

When connected, Claude shows a hammer icon confirming Blender tools are active:

Hammer icon


Example Prompts

Prompt

Demo

"Create a low poly dungeon with a dragon guarding gold"

Watch

"Beach scene with Poly Haven HDRIs, rocks, and vegetation"

Watch

"Recreate this reference image as a Blender scene"

Watch

"Export the scene and build a Three.js sketch from it"

Watch

"Generate a garden gnome with Hyper3D"

β€”

"Make this car red and metallic"

β€”

"Studio lighting, isometric camera"

β€”


Integrations

Poly Haven

Download HDRIs, textures, and 3D models. Enable in the BlenderMCP sidebar.

Hyper3D Rodin

AI 3D models. Free trial has a daily limit β€” get your own key at hyper3d.ai or fal.ai.

Hunyuan3D

Tencent 3D generation. Configure credentials in Blender addon preferences.

Sketchfab

Search and import 3D models into your scenes.


API Credentials

Store in Edit > Preferences > Add-ons > Blender MCP to persist across restarts:

Credential

Environment variable

Sketchfab API Key

BLENDERMCP_SKETCHFAB_API_KEY

Hyper3D API Key

BLENDERMCP_HYPER3D_API_KEY

Hunyuan3D SecretId

BLENDERMCP_HUNYUAN3D_SECRET_ID

Hunyuan3D SecretKey

BLENDERMCP_HUNYUAN3D_SECRET_KEY

Hunyuan3D API URL

BLENDERMCP_HUNYUAN3D_API_URL

export BLENDER_HOST=localhost
export BLENDER_PORT=9876

Troubleshooting

  • Confirm the addon server is running in the BlenderMCP sidebar

  • Do not run uvx manually β€” the client starts the server

  • First command often fails; try again

which uvx   # macOS / Linux
where uvx   # Windows

Use that full path as "command" in your config.

Break the request into smaller sequential prompts.

"args": ["--python", "3.11", "blender-mcp"],
"env": { "UV_PYTHON_PREFERENCE": "only-managed" }

Clear cache: uv cache clean blender-mcp && uvx --refresh blender-mcp

Restart your MCP client and the Blender server.


Technical Details

LLM Client  <-- MCP -->  MCP Server (src/blender_mcp/server.py)  <-- TCP:9876 -->  Blender Addon (addon.py)

JSON over TCP sockets:

{ "type": "create_object", "params": { "type": "SPHERE", "name": "Ball" } }
{ "status": "success", "result": { "name": "Ball", "location": [0, 0, 0] } }

Security and Telemetry

execute_blender_code runs arbitrary Python in Blender. Save your work before using it.

Optional anonymous usage stats (tool names, success/duration, version/platform) may be sent to help improve the project. Detailed fields (prompts/code/screenshots) require the addon privacy checkbox. Credential-like strings are stripped before upload.

Disable entirely:

BLENDER_MCP_DISABLE_TELEMETRY=true uvx blender-mcp

Or in client config: "env": { "BLENDER_MCP_DISABLE_TELEMETRY": "true" }

In Blender: Edit β†’ Preferences β†’ Add-ons β†’ Blender MCP β†’ telemetry checkbox.


Contributors

Made with contrib.rocks


Community

πŸ’¬ Discord

Join the community

πŸ“ Feedback

Share your thoughts

πŸ“ž Call

Schedule a call

πŸ› Issues

GitHub Issues

πŸ’– Sponsor

Support BlenderMCP

Supporters: CodeRabbit


Contributing

  1. Fork the repository

  2. Create a branch: git checkout -b feature/your-feature

  3. Commit and open a PR

See CONTRIBUTING.md and TERMS_AND_CONDITIONS.md.


License

MIT β€” see LICENSE.


Star History

Star History Chart


MCPBlender Β· blendermcp.org Β· Not affiliated with the Blender Foundation

⭐ Star the repo if it helps your workflow!

Available Tools

22 tools
download_polyhaven_assetB
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)
- user_prompt: The original user prompt that led to this tool call (for telemetry)

Returns a message indicating success or failure.

Inputs: asset_id (required), asset_type (required), resolution, file_format, +1 more.

download_sketchfab_modelA
Download and import a Sketchfab model by its UID.
The model will be scaled so its largest dimension equals target_size.

Parameters:
- uid: The unique identifier of the Sketchfab model
- target_size: REQUIRED. The target size in Blender units/meters for the largest dimension.
              You must specify the desired size for the model.
              Examples:
              - Chair: target_size=1.0 (1 meter tall)
              - Table: target_size=0.75 (75cm tall)
              - Car: target_size=4.5 (4.5 meters long)
              - Person: target_size=1.7 (1.7 meters tall)
              - Small object (cup, phone): target_size=0.1 to 0.3

Returns a message with import details including object names, dimensions, and bounding box.
The model must be downloadable and you must have proper access rights.

Inputs: uid (required), target_size (required), user_prompt.

execute_blender_codeA
Execute arbitrary Python code in Blender. Prefer small steps.

Pass either inline `code` or `file_path` to a local .py file (server reads
the file β€” cheaper than large inlined scripts). If both are set, `code` wins.

Parameters:
- code: Python source to execute (optional if file_path is set)
- file_path: Path to a local Python file (absolute or relative to server cwd)
- user_prompt: Original user prompt (telemetry)

Inputs: code, file_path, user_prompt.

generate_hunyuan3d_modelA
Generate 3D asset using Hunyuan3D by providing either text description, image reference, 
or both for the desired asset, and import the asset into Blender.
The 3D asset has built-in materials.

Parameters:
- text_prompt: (Optional) A short description of the desired model in English/Chinese.
- input_image_url: (Optional) The local or remote url of the input image. Accepts None if only using text prompt.

Returns: 
- When successful, returns a JSON with job_id (format: "job_xxx") indicating the task is in progress
- When the job completes, the status will change to "DONE" indicating the model has been imported
- Returns error message if the operation fails

Inputs: text_prompt, user_prompt, input_image_url.

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

Inputs: user_prompt, bbox_condition, input_image_urls, input_image_paths.

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

Inputs: text_prompt (required), user_prompt, bbox_condition.

get_hunyuan3d_statusB

Check if Hunyuan3D integration is enabled in Blender. Returns a message indicating whether Hunyuan3D features are available.

Inputs: user_prompt.

get_hyper3d_statusA

Check if Hyper3D Rodin integration is enabled in Blender. Returns a message indicating whether Hyper3D Rodin features are available.

Inputs: user_prompt.

get_object_infoB
Get detailed information about a specific object in the Blender scene.

Parameters:
- object_name: The name of the object to get information about
- user_prompt: The original user prompt that led to this tool call (for telemetry)

Inputs: object_name (required), user_prompt.

get_polyhaven_categoriesA
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)
- user_prompt: The original user prompt that led to this tool call (for telemetry)

Inputs: asset_type, user_prompt.

get_polyhaven_statusB

Check if PolyHaven integration is enabled in Blender. Returns a message indicating whether PolyHaven features are available.

Inputs: user_prompt.

get_scene_infoA

Get detailed information about the current Blender scene.

Includes blender_version and blender_version_string for API branching.

Parameters:
- user_prompt: Optional original user prompt (telemetry)

Inputs: user_prompt.

get_sketchfab_model_previewA
Get a preview thumbnail of a Sketchfab model by its UID.
Use this to visually confirm a model before downloading.

Parameters:
- uid: The unique identifier of the Sketchfab model (obtained from search_sketchfab_models)

Returns the model's thumbnail as an Image for visual confirmation.

Inputs: uid (required), user_prompt.

get_sketchfab_statusB

Check if Sketchfab integration is enabled in Blender. Returns a message indicating whether Sketchfab features are available.

Inputs: user_prompt.

get_viewport_screenshotA
Capture a screenshot of the current Blender 3D viewport.

Parameters:
- max_size: Maximum size in pixels for the largest dimension (default: 800)
- user_prompt: The original user prompt that led to this tool call (for telemetry)

Returns the screenshot as an Image.

Inputs: max_size, user_prompt.

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

Inputs: name (required), task_uuid, request_id.

import_generated_asset_hunyuanA
Import the asset generated by Hunyuan3D after the generation task is completed.

Parameters:
- name: The name of the object in scene
- zip_file_url: The zip_file_url given in the generate model step.

Return if the asset has been imported successfully.

Inputs: name (required), zip_file_url (required).

poll_hunyuan_job_statusA
Check if the Hunyuan3D generation task is completed.

For Hunyuan3D:
    Parameters:
    - job_id: The job_id given in the generate model step.

    Returns the generation task status. The task is done if status is "DONE".
    The task is in progress if status is "RUN".
    If status is "DONE", returns ResultFile3Ds, which is the generated ZIP model path
    When the status is "DONE", the response includes a field named ResultFile3Ds that contains the generated ZIP file path of the 3D model in OBJ format.
    This is a polling API, so only proceed if the status are finally determined ("DONE" or some failed state).

Inputs: job_id.

poll_rodin_job_statusA
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).

Inputs: request_id, subscription_key.

search_polyhaven_assetsA
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
- user_prompt: The original user prompt that led to this tool call (for telemetry)

Returns a list of matching assets with basic information.

Inputs: asset_type, categories, user_prompt.

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

Inputs: query (required), count, categories, user_prompt, +1 more.

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

Inputs: texture_id (required), object_name (required), user_prompt.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 22 tools

    Disambiguation4/5

    Each tool targets a specific operation (e.g., search, download, generate, poll, import) and provider (Polyhaven, Sketchfab, Hyper3D, Hunyuan3D), so ambiguity is low. The multiple generate/poll/import tools are distinguishable by their provider-specific names, though close reading is needed to avoid selecting the wrong integration.

    Naming Consistency3/5

    Most tools follow a verb_noun pattern with provider prefixes, but there are inconsistencies: 'import_generated_asset' lacks a provider suffix while 'import_generated_asset_hunyuan' includes it, and 'poll_rodin_job_status' uses 'rodin' instead of 'hyper3d'. These deviations prevent a perfect consistency score.

    Tool Count3/5

    With 22 tools, the server is on the heavy side, falling into the 16-25 range that feels crowded. However, the count is justified by the multiple external integrations (Polyhaven, Sketchfab, Hyper3D, Hunyuan3D), each requiring several distinct operations.

    Completeness3/5

    The tool set covers asset discovery, download, generation, and import for multiple providers, but core Blender manipulation is limited to info and screenshot tools plus an arbitrary code execution escape hatch. This makes the surface functional but incomplete for direct object manipulation workflows.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Connects Blender to Claude AI through the Model Context Protocol, enabling AI-assisted 3D modeling, scene creation, and manipulation through natural language commands.
      17
      2
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Connects Blender to Claude AI through the Model Context Protocol (MCP), enabling prompt-assisted 3D modeling, scene creation, and manipulation.
      17
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Connects Blender to Claude AI through the Model Context Protocol (MCP), enabling prompt-assisted 3D modeling, scene creation, and manipulation directly from Claude.
      17
      MIT