<div align="center">

MCP for Blender

Connect Blender to any LLM

formerly blender-mcp — the PyPI package is now mcp-for-blender. Existing setups keep working; no config change is required. Read more

Disclaimer: This is a third-party integration and not made by Blender

Prompt-assisted 3D modeling, scene creation, and manipulation — driven by AI.

Website · Full Tutorial · Discord · Sponsor · Buy me a coffee · Feedback

<a href="https://trendshift.io/repositories/14834?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-14834" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/14834" alt="ahujasid%2Fblender-mcp | Trendshift" width="250" height="55"/></a>

<br />

Supporters

CodeRabbit Kevin Guanche Darias Guillermo Rauch

All supporters: Support this project

</div>

---

Quickstart

Note: the PyPI package blender-mcp is now mcp-for-blender. Existing setups keep working — uvx blender-mcp still runs the server and no config change is required. New installs should use mcp-for-blender. What changed and why

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

<details open> <summary><b>Claude Desktop</b> — Settings → Developer → Edit Config</summary>

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

</details> <details> <summary><b>Claude Code</b></summary>

claude mcp add blender uvx mcp-for-blender

</details> <details> <summary><b>Codex</b></summary>

codex mcp add blender -- uvx mcp-for-blender

</details> <details> <summary><b>Cursor / VS Code / OpenCode / Antigravity</b></summary>

See MCP Client Setup below for per-client instructions and one-click install buttons.

</details>

3. Install the Blender addon

uvx mcp-for-blender 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

<details> <summary><b>Installing uv, per platform</b></summary>

macOS

brew install uv

Windows

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

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

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

It lands in ~/.local/bin — open a new shell so it's on your PATH.

Otherwise, installation instructions are on their website: Install uv

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.

</details>

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\<you>\.local\bin\uvx.exe.
• On Windows you can instead wrap it: "command": "cmd", "args": ["/c", "uvx", "mcp-for-blender"].
• After any PATH or config change, fully quit and relaunch the client (Windows: quit from the system tray, not just the window; macOS: <kbd>Cmd</kbd>+<kbd>Q</kbd>).

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", "mcp-for-blender"],
            "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 mcp-for-blender blender-mcp && uvx --refresh mcp-for-blender

Install without uv

On locked-down machines you can skip uvx entirely with pipx, then point your client at the installed command:

pipx install mcp-for-blender
pipx ensurepath          # then restart your shell / client

Use the resulting absolute path as "command" (find it with which mcp-for-blender / where mcp-for-blender) 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 mcp-for-blender .

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", "mcp-for-blender"]
        }
    }
}

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", "mcp-for-blender"]
        }
    }
}

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 mcp-for-blender --port 9877

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

{
  "mcpServers": {
    "blender": { "command": "uvx", "args": ["mcp-for-blender"] },
    "blender-b": { "command": "uvx", "args": ["mcp-for-blender", "--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