Install MCP for Blender: Advanced Setup and Configuration

This page covers everything beyond the basic quickstart: fixing PATH issues, pinning Python versions, installing without uv, managing the Blender addon, and upgrading from older versions.

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

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

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.

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.

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

When a new version of MCP for Blender is released, upgrade both the server package and the Blender addon.

1. Reinstall the addon

   uvx mcp-for-blender install-addon

2. Refresh the addon in Blender

   In Blender, go to Edit → Preferences → Add-ons, disable MCP for Blender, then re-enable it. Alternatively, restart Blender completely.

3. Reconnect

   In the 3D viewport, press N to open the sidebar, go to the MCP for Blender tab, and click Connect to MCP server.

4. Refresh the client config (if needed)

   If the server package itself was updated, delete the MCP for Blender entry from your client and re-add it so the client pulls the latest version.

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.