DOCSEARCHbyAlgolia
Submit Docs

BlenderMCP: Model Context Protocol Integration for Blender

repository·main·Indexed 12 days ago

https://github.com/ahujasid/blender-mcp

BlenderMCP version 1.8.0 is an integration using the Model Context Protocol (MCP) that allows AI agents, such as Claude, to control Blender via natural language. It consists of a Blender addon and a Python MCP server, enabling 3D modeling, scene manipulation, viewport screenshots, and the execution of arbitrary Python code. It also includes integrations for downloading assets from Poly Haven, Sketchfab, Hyper3D, and Hunyuan3D.

Tokens
4.8K
Snippets
12
Records
34
Agent score
98%

What's inside BlenderMCP

  1. What is BlenderMCP?

    main

    BlenderMCP is a Model Context Protocol (MCP) integration that connects Blender to Claude AI. It allows Claude to directly interact with and control Blender for prompt-assisted 3D modeling, scene creation, and manipulation.

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

  2. Security considerations for execute_blender_code

    main

    The execute_blender_code tool provides the ability to run arbitrary Python code directly within Blender.

    Warning: This is a powerful capability that can be dangerous. Always save your Blender work before executing code via this tool. Use caution when deploying in production environments.

  3. Understand the BlenderMCP communication protocol

    main

    BlenderMCP communicates using a JSON-based protocol over TCP sockets. The message structure is as follows:

    • Commands: Sent as JSON objects containing a type field and an optional params field.
    • Responses: Sent as JSON objects containing a status field and either a result or a message field.

  4. Review intellectual property and licensing terms

    main

    The intellectual property terms depend on your telemetry settings:

    • When Telemetry is Enabled: You grant the maintainer a worldwide, royalty-free, perpetual license to use your prompts, viewport images/screenshots, generated code, and captured scene metadata for AI training, research, and project improvement.
    • When Telemetry is Disabled: No license is granted as no data is collected.
    • Your Creative Work: You retain ownership of your original creative work.
    • AI-Generated Code: You may use AI-generated code however you like, but it is provided "as is" without guarantees. You are responsible for reviewing any AI-generated code before use.

  5. Understand data collection and usage in Blender MCP

    main

    Blender MCP collects certain data to improve the project and train AI models.

    Collected Data (if telemetry is enabled):

    • Prompts and text inputs provided to the AI
    • Generated code produced in response to prompts
    • Scene metadata (object names, modifier settings, configurations)
    • Basic usage data (timestamps, feature usage)
    • Images/screenshots of your Blender viewport

    Data Usage: Collected data may be used to train AI models for 3D creation and Blender automation, conduct research, and be released as part of anonymized open datasets.

    What is NOT collected:

    • Your Blender files or 3D models
    • Personal files unrelated to your Blender session
    • Passwords or financial information
    • Data from other applications on your system

  6. Install BlenderMCP without uv using pipx

    main

    If uv is not available, you can use pipx:

    1. Install the package: pipx install blender-mcp
    2. Ensure path is set: pipx ensurepath (then restart shell/client).
    3. Find the absolute path: which blender-mcp (macOS/Linux) or where blender-mcp (Windows).
    4. Use that absolute path as the command in your MCP client configuration and omit the args field.

  7. Install the BlenderMCP Addon

    main

    To enable the socket server within Blender, you must install the addon.py file:

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

  8. Install the MCP Server via uvx

    main

    The recommended way to run the MCP server is using the uv package manager.

    Prerequisites

    • Blender 3.0 or newer
    • Python 3.10 or newer
    • uv package manager installed via official installers (not pip install uv).

    Installation for Claude Desktop

    Edit your claude_desktop_config.json to include the following configuration:

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

    Installation for Cursor (Mac)

    Paste this into Settings > MCP (either as a global server or in .cursor/mcp.json for project-specific):

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

    Installation for Cursor (Windows)

    Paste this into Settings > MCP > Add Server:

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

  9. How to use BlenderMCP with Claude

    main

    Once the MCP server is configured in your client and the Blender addon is installed, follow these steps to start a session:

    1. In Blender: Open the 3D View sidebar (press N if not visible).
    2. In Blender: Locate the BlenderMCP tab.
    3. In Blender: (Optional) Check the Poly Haven box to enable asset API access.
    4. In Blender: Click Connect to Claude.
    5. In Claude: You should see a hammer icon representing the Blender MCP tools. You can now issue natural language commands like:
      • "Create a low poly scene in a dungeon..."
      • "Make this car red and metallic"
      • "Execute Python code to..."
      • "Download assets from Poly Haven..."

  11. Opt out of data collection and telemetry

    main

    To prevent the collection of prompts, generated code, scene metadata, and usage data, you can disable telemetry.

    How to opt out:

    1. Open the Blender MCP addon preferences.
    2. Uncheck the telemetry option.

    When telemetry is disabled, no data is collected, and you can continue using the software normally. No license is granted to the maintainer for your content when telemetry is disabled.

  12. Disable telemetry in BlenderMCP

    main

    BlenderMCP collects anonymous usage data. You can control or disable this via Blender settings or environment variables.

    Option 1: Via Blender Preferences

    Navigate to Edit > Preferences > Add-ons > Blender MCP and uncheck the telemetry consent checkbox.

    • Checked (Consent given): Collects anonymized prompts, code snippets, and screenshots.
    • Unchecked (Consent denied): Only collects minimal anonymous usage data (tool names, success/failure, duration).

    Option 2: Via Environment Variable

    To completely disable all telemetry, set the DISABLE_TELEMETRY environment variable to true.

    DISABLE_TELEMETRY=true uvx blender-mcp