Skip to main content
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:

​
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:
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.
Simply closing the window is not enough. You must fully quit the application so it reloads environment variables on next launch.

​
Windows Alternative

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

​
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:
If the server still fails to start, clear the uv cache and force a refresh:

​
Install Without uv

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

Install the server

2

Ensure pipx is on your PATH

3

Find the binary path

Use this full path as "command" in your MCP client config with no "args".

​
Installing the Blender Addon

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

Install automatically (recommended)

2

Enable the addon in Blender

Open Blender, then go to Edit → Preferences → Add-ons → Interface: Blender MCP 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 Blender MCP detected on your system:
To override the install location, set this environment variable before running the install command:

​
Upgrading

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

Reinstall the addon

2

Refresh the addon in Blender

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

Restart the MCP Server

In the 3D viewport, press N to open the sidebar, go to the BlenderMCP tab, and click Start MCP Server.
4

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.

​
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:
The server and addon must agree on the same host and port. If you change one, make sure the other matches.