blender-mcp-2.79 — Blender 2.79 compatibility fork

This is a fork of ahujasid/blender-mcp (MIT licensed, © 2025 Siddharth Ahuja — see LICENSE), patched so addon.py also runs on Blender 2.79 (Python 3.7). Upstream requires Blender 3.0+ / Python 3.10+; this fork exists for people who still run 2.79 for legacy tooling (e.g. Korman Myst-engine modding) and want the same MCP control there.

What changed, and why:

All of the above are hasattr/version-gated, so this same addon.py still works unmodified on modern Blender (3.0–5.x) — nothing upstream-compatible was removed, only extended. The MCP server/client half of this repo (src/blender_mcp/, the part launched via uvx blender-mcp) is unchanged from upstream — it's a separate, modern Python process (run via uv, not inside Blender) that just speaks the same JSON-over-TCP protocol to whichever addon.py is running inside Blender, so it works identically against a 2.79 or a 5.x Blender instance.

Getting true zero-click auto-start on Blender 2.79

On 2.80+, upstream auto-starts the socket server the instant the addon registers, using bpy.app.timers to safely hand control to the main thread — no user action needed. On 2.79, the underlying TCP server still auto-starts on launch (confirmed working — it doesn't need the timer API), but the main-thread command pump does not, because invoking any operator (including our modal pump) during addon registration hits Blender's restricted startup context (_RestrictContext, which lacks .scene and rejects bpy.ops calls).

This fork tries two automatic in-addon fallbacks — a load_post hook and a scene_update_post hook — but don't rely on either: load_post for the very first startup file load fires before addons finish registering (this is a known, documented Blender limitation, not a bug in this fork — see T34636), so appending a handler during register() is always too late for that specific event. scene_update_post only fires on an actual scene data mutation — on a genuinely idle session (no file opened, nothing touched) it may not fire for 30+ seconds, if at all.

The confirmed-reliable fix: launch Blender with the bundled --python script.

blender --python autostart_2.79.py

or double-click launch_with_mcp.bat (edit the BLENDER_EXE path inside it first to point at your own Blender 2.79 install). Scripts passed via --python run after Blender's full startup completes, in a normal non-restricted context — this is the standard, well-established pattern for unattended/pipeline Blender automation, and it starts the connection within a few seconds of launch with zero clicks. Verified end-to-end against a live session (auto-started, then a full round-trip execute_code call created and returned a real object).

If you'd rather not use a custom launcher, the fallback is a single manual step: click "Connect to Claude" once in the sidebar (View3D > N-panel > BlenderMCP tab) after Blender opens. It only takes one click per session.

One gotcha either way: if you load a different .blend file mid-session (File > Open or bpy.ops.wm.open_mainfile), Blender cancels the running modal pump along with it, and — since the pump is what lets execute_code run at all — you can't restart it through the same now-stuck MCP connection. Restart Blender with the target file passed directly (blender your_file.blend --python autostart_2.79.py) rather than opening it from within a running session.

Everything below this point is upstream's original README.

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.

Official website

Full tutorial

Join the Community

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

Supporters

CodeRabbit

All supporters:

Support this project

Highlights

For the current version and changelog, see the releases page.

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

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

Related MCP server: BlenderMCP

Features

• 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

Components

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

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

Linux: install uv with curl -LsSf https://astral.sh/uv/install.sh | sh (it lands in ~/.local/bin; open a new shell so it's on your PATH). On every OS, use uv's official installer above — not pip install uv, which may not create the uvx command and can hide uv inside an environment your client can't see.

⚠️ Do not proceed before installing UV

Make your client find uvx

MCP clients started from a GUI (Claude Desktop, Cursor, VS Code from the Dock/Start menu) do not inherit your terminal's PATH, so a bare "command": "uvx" can fail with spawn uvx ENOENT even though uvx works in your terminal. If that happens:

• Find uvx's full path — which uvx (macOS/Linux) or where uvx (Windows) — and use it as "command", e.g. /opt/homebrew/bin/uvx or C:\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 relaunch the client (Windows: quit from the system tray, not just the window; macOS: Cmd-Q).

Pin the Python version (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.11 still satisfies this package's requires-python >=3.10, and UV_PYTHON_PREFERENCE=only-managed keeps uv from selecting conda, pyenv, asdf, or system Python first. (The repo's .python-version is only a hint for contributors and does not affect uvx.) If a previous failed attempt keeps replaying after a fix, clear the cache: uv cache clean blender-mcp && uvx --refresh blender-mcp.

If uv won't work: install without 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.

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)

Example:

export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876

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

Use the Claude Code CLI to add the blender MCP server:

claude mcp add blender uvx blender-mcp

Cursor integration

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

Visual Studio Code Integration

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

OpenCode integration

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

Installing the Blender Addon

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"

Usage

Starting the Connection

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

Using with Claude

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.

Capabilities

• 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

Example Commands

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 integration

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.

Persistent API credentials

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:

• BLENDERMCP_SKETCHFAB_API_KEY

• BLENDERMCP_HYPER3D_API_KEY

• BLENDERMCP_HUNYUAN3D_SECRET_ID

• BLENDERMCP_HUNYUAN3D_SECRET_KEY

• BLENDERMCP_HUNYUAN3D_API_URL

Troubleshooting

• 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

Technical Details

Communication Protocol

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

Limitations & Security Considerations

• The execute_blender_code tool 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

Telemetry Control

BlenderMCP collects anonymous usage data to help improve the tool. You can control telemetry in two ways:

1. In Blender: Go to Edit > Preferences > Add-ons > Blender MCP and uncheck the telemetry consent checkbox

   • With consent (checked): Collects anonymized prompts, code snippets, and screenshots

   • Without consent (unchecked): Only collects minimal anonymous usage data (tool names, success/failure, duration)

2. Environment Variable: Completely disable all telemetry by running:

DISABLE_TELEMETRY=true uvx blender-mcp

Or add it to your MCP config:

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

All telemetry data is fully anonymized and used solely to improve BlenderMCP.

Feedback

We are actively looking for feedback on Blender MCP. If you have thoughts, share them here.

If you have more detailed feedback, you can schedule a call with us here - we will credit you in the project.

Contributing

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

Disclaimer

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