> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-for-blender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Blender MCP: Advanced Setup and Configuration

> Full installation guide for Blender MCP including PATH fixes, Python version pinning, pipx fallback, addon management, and upgrading from older versions.

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 Blender MCP, 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:

<CodeGroup>
  ```bash macOS/Linux theme={null}
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```

  ```powershell Windows theme={null}
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  ```
</CodeGroup>

## 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.

<Steps>
  <Step title="Find the full path to uvx">
    Run the appropriate command for your platform:

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      which uvx
      ```

      ```powershell Windows theme={null}
      where uvx
      ```
    </CodeGroup>

    Copy the full path that is printed.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  Simply closing the window is not enough. You must fully quit the application so it reloads environment variables on next launch.
</Warning>

### Windows Alternative

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

```json theme={null}
{
  "command": "cmd",
  "args": ["/c", "uvx", "blender-mcp"]
}
```

## 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:

```json theme={null}
{
  "command": "uvx",
  "args": ["--python", "3.11", "blender-mcp"],
  "env": {
    "UV_PYTHON_PREFERENCE": "only-managed"
  }
}
```

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

```bash theme={null}
uv cache clean blender-mcp && uvx --refresh blender-mcp
```

## Install Without uv

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

<Steps>
  <Step title="Install the server">
    ```bash theme={null}
    pipx install blender-mcp
    ```
  </Step>

  <Step title="Ensure pipx is on your PATH">
    ```bash theme={null}
    pipx ensurepath
    ```
  </Step>

  <Step title="Find the binary path">
    ```bash theme={null}
    which blender-mcp
    ```

    Use this full path as `"command"` in your MCP client config with no `"args"`.
  </Step>
</Steps>

## Installing the Blender Addon

The addon runs inside Blender and listens for commands from the MCP server.

<Steps>
  <Step title="Install automatically (recommended)">
    ```bash theme={null}
    uvx blender-mcp install-addon
    ```
  </Step>

  <Step title="Enable the addon in Blender">
    Open Blender, then go to **Edit → Preferences → Add-ons → Interface: Blender MCP** and enable it.
  </Step>
</Steps>

### Manual Installation

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

1. Download `addon.py` from the [GitHub repository](https://github.com/ahujasid/blender-mcp).
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 Blender MCP detected on your system:

```bash theme={null}
uvx blender-mcp addon-paths
```

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

```bash theme={null}
BLENDERMCP_ADDONS_DIR=/path/to/scripts/addons uvx blender-mcp install-addon
```

## Upgrading

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

<Steps>
  <Step title="Reinstall the addon">
    ```bash theme={null}
    uvx blender-mcp install-addon
    ```
  </Step>

  <Step title="Refresh the addon in Blender">
    In Blender, go to **Edit → Preferences → Add-ons**, disable **Blender MCP**, then re-enable it. Alternatively, restart Blender completely.
  </Step>

  <Step title="Restart the MCP Server">
    In the 3D viewport, press **N** to open the sidebar, go to the **BlenderMCP** tab, and click **Start MCP Server**.
  </Step>

  <Step title="Refresh the client config (if needed)">
    If the server package itself was updated, delete the Blender MCP entry from your client and re-add it so the client pulls the latest version.
  </Step>
</Steps>

## Environment Variables

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

| Variable       | Default     | Purpose                                 |
| -------------- | ----------- | --------------------------------------- |
| `BLENDER_HOST` | `localhost` | Host address the MCP server connects to |
| `BLENDER_PORT` | `9876`      | TCP port the addon listens on           |

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

```json theme={null}
{
  "command": "uvx",
  "args": ["blender-mcp"],
  "env": {
    "BLENDER_HOST": "127.0.0.1",
    "BLENDER_PORT": "9876"
  }
}
```

<Note>
  The server and addon must agree on the same host and port. If you change one, make sure the other matches.
</Note>