Install MCP for Blender: Advanced Setup and Configuration

This page covers everything beyond the basic quickstart: installer options, manual setup, fixing PATH issues, installing without uv, managing the Blender addon, and upgrading.

One-Command Install

The installer configures your MCP clients and the Blender addon in one go:

curl -LsSf https://www.mcp-for-blender.com/install.sh | sh

irm https://www.mcp-for-blender.com/install.ps1 | iex

Prefer not to run a script, or Windows Defender blocked it? Install uv with winget, open a new terminal, then run setup:

winget install --id=astral-sh.uv -e
uvx mcp-for-blender setup

It installs uv if it's missing, then runs uvx mcp-for-blender setup, which:

• Detects Claude Desktop, Claude Code, Codex, Cursor, VS Code, Devin Desktop/Windsurf, OpenCode, and Antigravity, and asks which to configure
• Adds a blender server entry that calls uvx by its full path, so GUI apps that don't inherit your terminal PATH still find it
• Merges into your existing config, keeping other servers and saving a .bak of each file it changes
• Installs the Blender addon and enables it

Pass options to control what it does:

uvx mcp-for-blender setup --dry-run
# or through the installer:
curl -LsSf https://www.mcp-for-blender.com/install.sh | sh -s -- --dry-run

Running setup again is safe: clients that are already configured are left alone, and entries using the old blender-mcp package are offered an update.

Manual Setup

To set things up by hand, install uv, add the server to your client (MCP Clients), then install the addon.

Prerequisites

Before you install MCP for Blender, make sure your system meets these requirements:

• Blender 3.0 or newer
• Python 3.10 or newer
• uv package manager (recommended)

Install uv using the official installer for your platform:

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

winget install --id=astral-sh.uv -e

Make Your Client Find uvx

GUI clients like Claude Desktop, Cursor, and VS Code do not inherit your terminal PATH. This means they often cannot find uvx even though it works in your shell.

1. Find the full path to uvx

   Run the appropriate command for your platform:

   which uvx

   where uvx

   Copy the full path that is printed.

2. Use the full path in your client config

   In your MCP client configuration, set "command" to the full path you copied instead of just uvx.

3. Fully quit and relaunch the client

   After any PATH or config change, completely quit the client. On macOS, use Cmd+Q. On Windows, quit from the system tray. Then reopen it.

Windows Alternative

If the full path approach does not work on Windows, wrap the call through cmd:

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

Pin the Python Version

If you use conda, pyenv, or asdf, the client may pick a different Python than expected. Pin Python 3.11 explicitly in your MCP config:

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

If the server still fails to start, clear the uv cache and force a refresh:

uv cache clean mcp-for-blender blender-mcp && uvx --refresh mcp-for-blender

Install Without uv

If you prefer not to use uv, install with pipx instead.

1. Install the server

   pipx install mcp-for-blender

2. Ensure pipx is on your PATH

   pipx ensurepath

3. Find the binary path

   which mcp-for-blender

   Use this full path as "command" in your MCP client config with no "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 root of the GitHub repository:

docker build -t mcp-for-blender .

Then point your MCP client at it. The -i flag is required because 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.

Installing the Blender Addon

The addon runs inside Blender and listens for commands from the MCP server. The one-command installer does all of this for you; the steps below are for doing it by hand.

1. Install automatically (recommended)

   uvx mcp-for-blender install-addon

2. Enable the addon in Blender

   Open Blender, then go to Edit → Preferences → Add-ons → Interface: MCP for Blender and enable it.

Once enabled, the addon starts its server whenever Blender opens. To check, press N in the 3D viewport and open the MCP for Blender tab.

Manual Installation

If the automatic installer does not work, install the addon manually:

1. Download addon.py from the GitHub repository.
2. In Blender, go to Edit → Preferences → Add-ons → Install.
3. Select the downloaded addon.py file.
4. Enable the addon from the list.

Addon Path Options

To see which addon directories MCP for Blender detected on your system:

uvx mcp-for-blender addon-paths

To override the install location, set this environment variable before running the install command:

BLENDERMCP_ADDONS_DIR=/path/to/scripts/addons uvx mcp-for-blender install-addon

Upgrading

To update an existing install, run:

uvx mcp-for-blender@latest update

This updates both halves in one go:

• Server: refreshes uv's cached copy of mcp-for-blender (or upgrades it if you used uv tool install), so your MCP clients launch the new release next time.
• Addon: updates every installed copy of the Blender addon, keeping a .bak of each file it replaces. It never downgrades an addon that's newer than the release, and leaves alone a copy you've edited locally.

Add --dry-run to see what it would change without changing anything.

Then:

1. Restart your MCP client (Claude Desktop, Cursor, ...) so it starts the new server.
2. Restart Blender, or go to Preferences → Add-ons, disable and re-enable Interface: MCP for Blender, then click Start MCP Server again.

If a client is still set up with the old blender-mcp package name, update tells you; run uvx mcp-for-blender setup to switch it over.

Updating from inside Blender: The addon also checks GitHub for a newer version when Blender starts. When one is available, click Update Addon in the MCP for Blender sidebar tab, then restart Blender. You can also click Check for Updates there. This updates only the addon, not the server.

Environment Variables

You can customize the connection between the MCP server and the Blender addon using these environment variables:

Set them in your MCP client config or in your shell before starting the server:

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

You can also pass --host and --port as CLI flags (for example "args": ["mcp-for-blender", "--port", "9877"]), which take precedence over the environment variables. See the Configuration reference for running several Blender instances side by side.