---

Quickstart

Three steps: install uv, point your MCP client at the server, install the Blender addon.

1. Install uv

# macOS
brew install uv
Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Warning: Do not proceed before installing uv. Use the official installer — not pip install uv.

2. Add the MCP server to your client

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

claude mcp add blender uvx blender-mcp

codex mcp add blender -- uvx blender-mcp

3. Install the Blender addon

uvx blender-mcp install-addon

Then in Blender: Edit → Preferences → Add-ons → enable Interface: MCP for Blender.

4. Connect

In Blender's 3D viewport, press N → open the MCP for Blender tab → click Start MCP Server. That's it — ask Claude to build something.

Note: Only run one instance of the MCP server (either Cursor or Claude Desktop), not both.

---

Table of Contents

• Quickstart
• Features
• Components
• Installation
• Prerequisites
• Make your client find uvx
• Pin the Python version
• Install without uv
• Run with Docker
• Environment Variables
• MCP Client Setup
• Claude for Desktop
• Codex
• Cursor
• Visual Studio Code
• OpenCode
• Antigravity
• Installing the Blender Addon
• Upgrading (existing users)
• Usage
• Starting the Connection
• Using with Claude
• Capabilities
• Example Commands
• Persistent API Credentials
• Troubleshooting
• Technical Details
• Limitations & Security Considerations
• Telemetry Control
• Feedback
• Contributing
• Disclaimer
• Star History

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 | | Asset & model generation | Poly Haven assets, Sketchfab models, Poly Pizza low-poly models, and AI-generated 3D models via Hyper3D Rodin and Hunyuan3D |

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

brew install uv

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

$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

Warning: 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\\.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

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.

Run with Docker

You can run the MCP server in a container instead of installing it. Blender itself still runs on your machine — the container only hosts the MCP server, which connects out to the Blender addon.

Build the image from the repo root:

docker build -t blender-mcp .

Then point your MCP client at it (the -i flag is required — the server talks to the client over stdin/stdout):

{
    "mcpServers": {
        "blender": {
            "command": "docker",
            "args": ["run", "-i", "--rm", "blender-mcp"]
        }
    }
}

The image defaults to BLENDER_HOST=host.docker.internal, which reaches the host's Blender out of the box with Docker Desktop on macOS and Windows.

On Linux, host.docker.internal doesn't exist and the addon only listens on localhost, so use host networking instead:

{
    "mcpServers": {
        "blender": {
            "command": "docker",
            "args": ["run", "-i", "--rm", "--network=host", "-e", "BLENDER_HOST=localhost", "blender-mcp"]
        }
    }
}

To enable safe mode in the container, add "-e", "BLENDER_MCP_SAFE_MODE=1" to args.

Environment Variables

The following environment variables can be used to configure the Blender connection:

| Variable | Default | Description | |---|---|---| | BLENDER_HOST | localhost | Host address for Blender socket server | | BLENDER_PORT | 9876 | Port number for Blender socket server | | BLENDER_MCP_SAFE_MODE | off | Set to 1 to validate scripts before they run in Blender (see below) |

Example:

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

You can also pass the connection as CLI flags, which take precedence over the environment variables. This is handy for running several Blender instances side by side, since each MCP client entry can point at a different port with plain arguments instead of env vars:

uvx blender-mcp --port 9877

In an MCP client config that means a second entry differing only in args:

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

Each instance needs its own port set in the Blender addon panel to match.

Note: the addon's socket server has no authentication or encryption, so

anyone who can reach that port can run Python inside Blender. Keep it on

localhost unless you are on a trusted network, and prefer an SSH tunnel over

pointing --host/BLENDER_HOST at a remote machine directly.

Safe mode

By default, the AI can run any Python code in Blender. Set BLENDER_MCP_SAFE_MODE=1 to check every script before it runs and block risky code — things like reading or writing files directly, running other programs, accessing the network, or installing code that keeps running after the script ends. Normal Blender work (modeling, materials, rendering, saving, import/export) still works. Blocked scripts are sent back to the AI with the reason, so it can try again with a corrected version.

---

MCP Client Setup

Claude for Desktop

Watch the setup instruction video (assuming you have already installed uv)

Go to Claude → Settings → Developer → Edit Config → claude_desktop_config.json and include the following:

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

claude mcp add blender uvx blender-mcp

Codex

The Codex CLI, desktop app, and IDE extension all share the same config file (~/.codex/config.toml), so setting the server up once covers all three.

Register the server with the Codex CLI:

codex mcp add blender -- uvx blender-mcp

Or add it by hand to ~/.codex/config.toml (or $CODEX_HOME/config.toml):

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

Or in the Codex desktop app: Settings → MCP servers → Add server → name it blender, pick STDIO, enter uvx blender-mcp as the command, then Save and restart. If the app can't find uvx, use its full path instead — see Make your client find uvx.

Check it registered with codex mcp list — the blender server should show as enabled. The tools become available the next time you start Codex.

To set environment variables (e.g. a non-default Blender host/port), pass --env KEY=VALUE flags to codex mcp add, or add them in the config file:

[mcp_servers.blender]
command = "uvx"
args = ["blender-mcp"]
env = { BLENDER_HOST = "localhost", BLENDER_PORT = "9876" }

Cursor

macOS — go to Settings → MCP and paste the following:

• To use as a global server, use the "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"
            ]
        }
    }
}

Windows — 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

Note: Only run one instance of the MCP server (either on Cursor or Claude Desktop), not both.

Visual Studio Code

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

OpenCode

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

Antigravity

{
  "mcpServers": {
    "blender-mcp": {
      "command": "uvx",
      "args": ["blender-mcp"],
      "env": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }
    }
  }
}

---

Installing the Blender Addon

1. Recommended — from a terminal, run:

uvx blender-mcp install-addon

This copies the addon into your Blender addons folder as blender_mcp.py. It prints where it wrote to, and keeps a .bak of any file it replaces.

Optional: uvx blender-mcp addon-paths lists detected Blender addons folders. Override the destination with BLENDERMCP_ADDONS_DIR=/path/to/scripts/addons.

2. Open Blender

3. Go to Edit → Preferences → Add-ons

4. Enable Interface: MCP for Blender (search "MCP for Blender"). If it doesn't appear yet, click Install… and select the copied blender_mcp.py / addon.py, or restart Blender.

5. Manual alternative — if the command above can't find your Blender install, or you prefer doing it by hand: download addon.py from this repo → in Blender, Edit → Preferences → Add-ons → Install… → select the downloaded addon.py → enable it.

Then open the MCP for Blender tab in Blender's sidebar (press N in the 3D viewport) and click Start MCP Server. See Starting the Connection below.

Upgrading (existing users)

For newcomers, go straight to Quickstart. For existing users, see below.

1. Update the addon file by running:

uvx blender-mcp install-addon
uvx blender-mcp addon-paths   # optional: list detected Blender addons folders

2. In Blender: Preferences → Add-ons → disable and re-enable Interface: MCP for Blender (or restart Blender), then click Start MCP Server again.

3. Delete the MCP server from Claude and add it back again if the server package itself needs a refresh.

Note: the MCP server never modifies your Blender addon files on its own. When it starts, it checks whether the installed addon is behind the bundled copy and logs how to update; install-addon is what actually writes, and it keeps a .bak of the file it replaces. Trajectory capture still works on older loaded addons via an execute_code fallback.

---

Usage

Starting the Connection

1. In Blender, go to the 3D View sidebar (press N if not visible) 2. Find the MCP for Blender tab 3. Turn on the checkboxes you'd like to use (see more under Capabilities below) 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 MCP for Blender.

Capabilities

• Get scene and object information
• Create, delete and modify shapes
• Apply or create materials for objects
• Execute any Python code in Blender
• Export the scene, the selection or named objects to GLB/FBX for other applications (export_scene)
• Look up node schemas and the bpy API reference instead of guessing socket order or enum names
• Download the right models, assets and HDRIs through Poly Haven
• Search and download models from Sketchfab
• Search and download low-poly models from Poly Pizza
• AI generated 3D models through Hyper3D Rodin and Hunyuan3D

Hunyuan3D on Tencent Cloud (Official API mode)

Which Tencent Cloud service the addon must call depends on where your account lives:

| Account | Service the addon calls | Region | Sidebar toggle | |---|---|---|---| | Mainland (cloud.tencent.com) | AI3D 3.0 (ai3d, version 2025-05-13) | ap-guangzhou | leave International (Pro) account off (default) | | International (tencentcloud.com), Hunyuan-to-3D (Professional) | hunyuan, version 2023-09-01, PBR enabled | ap-singapore | tick International (Pro) account |

International credentials sent to the mainland endpoint fail with AuthFailure.SignatureFailure or ResourceUnavailable, so tick the toggle when your SecretId/SecretKey come from tencentcloud.com. The toggle sits under Tencent Hunyuan 3D → Official API in the sidebar.

Poly Pizza

Poly Pizza hosts roughly 10,600 free low-poly models, including the rescued Google Poly archive. It is the best source for stylised game assets: every model is a single self-contained .glb, and the geometry is far lighter than Sketchfab's.

1. Get a free API key at poly.pizza/settings/api 2. In the 3D View sidebar, tick Use assets from Poly Pizza 3. Paste the key into the API Key field that appears (or store it permanently under Edit → Preferences → Add-ons → MCP for Blender)

Worked example:

"Search Poly Pizza for a low-poly chair under a CC0 licence and import one at 1 metre tall"

Claude calls search_polypizza_models(query="chair", licence="CC0"), which returns each match with its licence and triangle count, then download_polypizza_model(model_id="...", normalize_size=True, target_size=1.0).

You can also filter by category ("Animals", "Furniture & Decor", "Transport", "Nature", "Buildings", "People & Characters", "Food & Drink", "Weapons", "Clutter", "Objects", "Scenes & Levels", "Other") or ask for animated models only.

Attribution: about 69% of the Poly Pizza catalogue is CC-BY, which requires you to credit the creator wherever the model appears. On import, the ready-formatted credit line is written onto each imported root object as the custom property polypizza_attribution (alongside polypizza_id and polypizza_licence), so it is saved into your .blend and survives the session. Filter with licence="CC0" if you would rather use models that need no credit.

Example Commands

Here are some examples of what you can ask Claude to do:

| Prompt | Demo | |---|---| | "Create a low poly scene in a dungeon, with a dragon guarding a pot of gold" | Watch | | "Create a beach vibe using HDRIs, textures, and models like rocks and vegetation from Poly Haven" | Watch | | Give a reference image, and create a Blender scene out of it | Watch | | "Get information about the current scene, and make a threejs sketch from it" | Watch | | "Generate a 3D model of a garden gnome through Hyper3D" | | | "Fill this room with low-poly furniture from Poly Pizza" | | | "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" | |

---

Persistent API Credentials

MCP for Blender supports persistent credentials via Blender Add-on Preferences:

Edit → Preferences → Add-ons → MCP for Blender

You can store these values there so they survive Blender restarts:

• Sketchfab API Key
• Poly Pizza API Key
• Hyper3D API Key
• Hunyuan3D SecretId / SecretKey
• Hunyuan3D API URL

| Variable | |---| | BLENDERMCP_SKETCHFAB_API_KEY | | BLENDERMCP_POLYPIZZA_API_KEY | | BLENDERMCP_HYPER3D_API_KEY | | BLENDERMCP_HUNYUAN3D_SECRET_ID | | BLENDERMCP_HUNYUAN3D_SECRET_KEY | | BLENDERMCP_HUNYUAN3D_API_URL |

---

Troubleshooting

| Problem | Fix | |---|---| | 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. | | Poly Pizza download fails with a Cloudflare challenge | static.poly.pizza is behind bot protection and blocks datacenter, VPN and cloud IPs. Your API key is fine - the CDN never sees it. Retry from a normal connection, or download the .glb by hand and use File → Import → glTF 2.0. | | **