Metadata-Version: 2.4
Name: blender-mcp-cli
Version: 1.6.2
Summary: Direct command-line control for the Blender MCP add-on
Author: mcplato-ai
License-Expression: MIT
Project-URL: Homepage, https://github.com/mcplato-ai/blender-mcp
Project-URL: Bug Tracker, https://github.com/mcplato-ai/blender-mcp/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: legacy-mcp
Requires-Dist: mcp[cli]>=1.3.0; extra == "legacy-mcp"
Requires-Dist: httpx>=0.27.0; extra == "legacy-mcp"
Dynamic: license-file



# Blender MCP CLI

`blender-mcp-cli` lets scripts, agents, and LLM runners control the unchanged
BlenderMCP add-on directly through its TCP/JSON socket, without an MCP host. The
repository also retains the original MCP server source as an optional legacy
integration.

**[Official website](https://blendermcp.org/)**

[Full tutorial](https://www.youtube.com/watch?v=lCyQ717DuzQ)

### Join the Community

Give feedback, get inspired, and build on top of the MCP: [Discord](https://discord.gg/z5apgR8TFU)

### Supporters

[CodeRabbit](https://www.coderabbit.ai/)

**All supporters:**

[Support this project](https://github.com/sponsors/ahujasid)

## Highlights

For the current version and changelog, see the [releases page](https://github.com/mcplato-ai/blender-mcp/releases).

- Added Hunyuan3D support
- View screenshots for Blender viewport to better understand the scene
- Search and download Sketchfab models
- Support for Poly Haven assets through their API
- Support to generate 3D models using Hyper3D Rodin
- Run Blender MCP on a remote host
- Telemetry for tools executed (completely anonymous)

### Installing a new version (existing users)
- For newcomers, you can go straight to Installation. For existing users, see the points below
- Run `blender-mcp-cli --pretty skill path` and replace the Blender add-on with
  the version-matched file reported as `addon_path`. The same `addon.py` is also
  attached directly to every GitHub Release.
- Delete the MCP server from Claude and add it back again, and you should be good to go!


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

## Components

The repository contains three client/server layers:

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
3. **Direct CLI (`src/blender_mcp/cli.py`)**: A Python command-line client that talks to the Blender addon directly without MCP

The Blender addon uses raw TCP with JSON messages on `localhost:9876`. It is not
an HTTP server. Both Python clients use the same unchanged addon protocol.

## Direct CLI (No MCP)

The `blender-mcp-cli` command is intended for scripts, agents, and LLM clients that
do not want an MCP host. It uses only the existing Blender addon socket and does
not import or start FastMCP.

Install the package and locate its version-matched Blender add-on:

```bash
pipx install blender-mcp-cli
blender-mcp-cli --help
blender-mcp-cli --pretty skill path
```

Select the returned `result.addon_path` in Blender's
`Edit > Preferences > Add-ons > Install...`, enable the add-on, and start its
socket from the `BlenderMCP` sidebar. Then verify the direct client:

```bash
blender-mcp-cli --pretty schema
blender-mcp-cli --pretty status all
```

Alternatively use `uv tool install blender-mcp-cli`. For a source checkout,
run `python -m pip install -e .` from the repository root.

Common operations:

```bash
# Inspect Blender
blender-mcp-cli --pretty scene info
blender-mcp-cli --pretty object info Cube

# Execute multiline Blender Python without shell quoting
blender-mcp-cli code exec --file create_scene.py
printf 'print(bpy.app.version_string)' | blender-mcp-cli code exec --stdin

# Capture the current viewport
blender-mcp-cli viewport screenshot ./viewport.png --max-size 1000

# Call any current or future addon command directly
blender-mcp-cli raw call get_object_info --params '{"name":"Cube"}'
```

The command tree also covers Poly Haven, Sketchfab, Hyper3D Rodin, and
Hunyuan3D. Run help at any level:

```bash
blender-mcp-cli polyhaven --help
blender-mcp-cli sketchfab download --help
blender-mcp-cli hyper3d generate-images --help
blender-mcp-cli hunyuan3d generate --help
```

### CLI contract for LLM clients

- Run `blender-mcp-cli schema` for a machine-readable capability catalog.
- Successful commands write exactly one JSON object to stdout and exit `0`.
- Runtime errors write exactly one JSON object to stderr and use stable non-zero exit codes.
- A timeout is never retried automatically because the Blender command may already have executed.
- `code exec` runs arbitrary Python inside Blender and must only be used with trusted input.
- Screenshot paths are interpreted by Blender and must be visible to both processes.

### Codex Skill

Every GitHub Release publishes a standalone
`blender-mcp-cli-skill-X.Y.Z.zip` containing the installable Skill and the exact
version-matched Blender `addon.py`. With a current GitHub CLI, install only the
latest tagged Skill at user scope:

```bash
gh skill install mcplato-ai/blender-mcp blender-mcp-cli \
  --agent codex --scope user
```

Alternatively, download the standalone ZIP from the GitHub Release and extract
it directly into the Codex skills directory:

```bash
gh release download \
  --repo mcplato-ai/blender-mcp \
  --pattern 'blender-mcp-cli-skill-*.zip'

unzip blender-mcp-cli-skill-X.Y.Z.zip \
  -d "${CODEX_HOME:-$HOME/.codex}/skills"
```

The archive already contains the top-level `blender-mcp-cli/` directory. Start
a new Codex session after installation so Codex discovers it. The standalone
Skill does not install the Python CLI; install `blender-mcp-cli` separately
before controlling Blender.

The wheel and source distribution also publish the same Skill together with
the CLI. The release workflow injects the repository-root `addon.py` into the
wheel and standalone Skill without maintaining a second source copy. Install
or inspect that bundled copy with:

```bash
blender-mcp-cli skill path
blender-mcp-cli skill install
```

`skill path` reports an explicit `addon_path`. Select that file from Blender's
`Edit > Preferences > Add-ons > Install...`. `skill install` also copies the
same file into the installed Skill directory.

The default destination is
`${CODEX_HOME:-~/.codex}/skills/blender-mcp-cli`. Use
`blender-mcp-cli skill install --help` for `--target` and safe overwrite
options. Invoke `$blender-mcp-cli` when an agent needs the environment setup,
direct CLI workflow, timeout rules, and visual verification sequence in
context.

For a source checkout, the same commands use
`skills/blender-mcp-cli/SKILL.md` directly, so local Skill changes can be tested
before publishing.

The default connection can be overridden with `BLENDER_HOST`, `BLENDER_PORT`,
`BLENDER_CONNECT_TIMEOUT`, and `BLENDER_TIMEOUT`, or the corresponding CLI
options. Since the unchanged addon binds to localhost, remote use should go
through a controlled tunnel rather than exposing the socket publicly.

### Publishing

The GitHub workflow builds and tests every push and pull request. Publishing is
triggered by pushing a `vX.Y.Z` tag that matches the version in
`pyproject.toml`. The workflow creates a draft GitHub Release, attaches and
verifies the standalone Skill ZIP, wheel, source distribution, and the direct
Blender `addon.py`, publishes the Release, and only then publishes the Python
distributions to PyPI. This ordering supports immutable GitHub Releases and
leaves every built artifact available from GitHub even when PyPI is temporarily
unavailable.

Configure a PyPI Trusted Publisher for repository `mcplato-ai/blender-mcp`,
workflow `publish.yml`, and environment `pypi`; no long-lived PyPI token is
required in GitHub secrets. Before the first upload, create a Pending Publisher
for project `blender-mcp-cli` with owner `mcplato-ai`, repository
`blender-mcp`, workflow `publish.yml`, and environment `pypi`. PyPI rejects the
OIDC exchange with `invalid-publisher` until this one-time account setting
exists.

A maintainer with a current GitHub CLI can validate the Skill and create the
release that triggers both publications:

```bash
gh skill publish --dry-run
git tag vX.Y.Z
git push origin vX.Y.Z
```

## Installation

The sections below document the optional legacy MCP server. From a source
checkout, install it with `python -m pip install -e '.[legacy-mcp]'` and run
`python -m blender_mcp.server`. Direct CLI users do not need this extra.


### Prerequisites

- Blender 3.0 or newer
- Python 3.10 or newer
- uv package manager: 

**If you're on Mac, please install uv as**
```bash
brew install uv
```
**On Windows**
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex" 
```
and then add uv to the user path in Windows (you may need to restart Claude Desktop after):
```powershell
$localBin = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User")
```

Otherwise installation instructions are on their website: [Install uv](https://docs.astral.sh/uv/getting-started/installation/)

**Linux:** install uv with `curl -LsSf https://astral.sh/uv/install.sh | sh` (it lands in `~/.local/bin`; open a new shell so it's on your PATH). 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.

**⚠️ 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", "blender-mcp"]`.
- After any PATH or config change, **fully quit and relaunch** the client (Windows: quit from the system tray, not just the window; macOS: Cmd-Q).

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

```json
{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["--python", "3.11", "blender-mcp"],
            "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 blender-mcp && uvx --refresh blender-mcp`.

### If uv won't work: install without uv

On locked-down machines you can skip uvx entirely with [`pipx`](https://pipx.pypa.io), then point your client at the installed command:

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

Use the resulting absolute path as `"command"` (find it with `which blender-mcp` / `where blender-mcp`) and omit `args`.

### Environment Variables

The following environment variables can be used to configure the Blender connection:

- `BLENDER_HOST`: Host address for Blender socket server (default: "localhost")
- `BLENDER_PORT`: Port number for Blender socket server (default: 9876)

Example:
```bash
export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876
```

### Claude for Desktop Integration

[Watch the setup instruction video](https://www.youtube.com/watch?v=neoK_WMq92g) (Assuming you have already installed uv)

Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:

```json
{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": [
                "blender-mcp"
            ]
        }
    }
}
```
<details>
<summary>Claude Code</summary>

Use the Claude Code CLI to add the blender MCP server:

```bash
claude mcp add blender uvx blender-mcp
```
</details>

### Cursor integration

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/link/mcp%2Finstall?name=blender&config=eyJjb21tYW5kIjoidXZ4IGJsZW5kZXItbWNwIn0%3D)

For Mac users, go to Settings > MCP and paste the following 

- To use as a global server, use "add new global MCP server" button and paste
- To use as a project specific server, create `.cursor/mcp.json` in the root of the project and paste


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

For Windows users, go to Settings > MCP > Add Server, add a new server with the following settings:

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

[Cursor setup video](https://www.youtube.com/watch?v=wgWsJshecac)

**⚠️ Only run one instance of the MCP server (either on Cursor or Claude Desktop), not both**

### Visual Studio Code Integration

_Prerequisites_: Make sure you have [Visual Studio Code](https://code.visualstudio.com/) installed before proceeding.

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_blender--mcp_server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=ffffff)](vscode:mcp/install?%7B%22name%22%3A%22blender-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22blender-mcp%22%5D%7D)

### OpenCode integration

```json
{
  "mcp": {
    "blender-mcp": {
      "type": "local",
      "command": ["uvx", "blender-mcp"],
      "enabled": true,
      "environment": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }   
    }
  }
}
```

### Installing the Blender Addon

1. Run `blender-mcp-cli --pretty skill path` and note the returned
   `addon_path`. Alternatively, download the `addon.py` asset from the matching
   GitHub Release.
2. Open Blender.
3. Go to Edit > Preferences > Add-ons.
4. Click "Install..." and select that `addon.py` file.
5. Enable the addon by checking the box next to "Interface: Blender MCP".


## Usage

### Starting the Connection
![BlenderMCP in the sidebar](assets/addon-instructions.png)

1. In Blender, go to the 3D View sidebar (press N if not visible)
2. Find the "BlenderMCP" tab
3. Turn on the Poly Haven checkbox if you want assets from their API (optional)
4. Click "Connect to Claude"
5. Make sure the MCP server is running in your terminal

### Using with Claude

Once the config file has been set on Claude, and the addon is running on Blender, you will see a hammer icon with tools for the Blender MCP.

![BlenderMCP in the sidebar](assets/hammer-icon.png)

#### Capabilities

- Get scene and object information 
- Create, delete and modify shapes
- Apply or create materials for objects
- Execute any Python code in Blender
- Download the right models, assets and HDRIs through [Poly Haven](https://polyhaven.com/)
- AI generated 3D models through [Hyper3D Rodin](https://hyper3d.ai/)


### Example Commands

Here are some examples of what you can ask Claude to do:

- "Create a low poly scene in a dungeon, with a dragon guarding a pot of gold" [Demo](https://www.youtube.com/watch?v=DqgKuLYUv00)
- "Create a beach vibe using HDRIs, textures, and models like rocks and vegetation from Poly Haven" [Demo](https://www.youtube.com/watch?v=I29rn92gkC4)
- Give a reference image, and create a Blender scene out of it [Demo](https://www.youtube.com/watch?v=FDRb03XPiRo)
- "Generate a 3D model of a garden gnome through Hyper3D"
- "Get information about the current scene, and make a threejs sketch from it" [Demo](https://www.youtube.com/watch?v=jxbNI5L7AH8)
- "Make this car red and metallic" 
- "Create a sphere and place it above the cube"
- "Make the lighting like a studio"
- "Point the camera at the scene, and make it isometric"

## Hyper3D integration

Hyper3D's free trial key allows you to generate a limited number of models per day. If the daily limit is reached, you can wait for the next day's reset or obtain your own key from hyper3d.ai and fal.ai.

## Persistent API credentials

BlenderMCP supports persistent credentials via Blender Add-on Preferences:

`Edit -> Preferences -> Add-ons -> Blender MCP`

You can store these values there so they survive Blender restarts:

- Sketchfab API Key
- Hyper3D API Key
- Hunyuan3D SecretId / SecretKey
- Hunyuan3D API URL

For headless setups or CI, credentials can also be injected by environment variables:

- `BLENDERMCP_SKETCHFAB_API_KEY`
- `BLENDERMCP_HYPER3D_API_KEY`
- `BLENDERMCP_HUNYUAN3D_SECRET_ID`
- `BLENDERMCP_HUNYUAN3D_SECRET_KEY`
- `BLENDERMCP_HUNYUAN3D_API_URL`

## Troubleshooting

- **Connection issues**: Make sure the Blender addon server is running, and the MCP server is configured on Claude, DO NOT run the uvx command in the terminal. Sometimes, the first command won't go through but after that it starts working.
- **Timeout errors**: Try simplifying your requests or breaking them into smaller steps
- **Poly Haven integration**: Claude is sometimes erratic with its behaviour
- **Have you tried turning it off and on again?**: If you're still having connection errors, try restarting both Claude and the Blender server


## Technical Details

### Communication Protocol

The system uses a simple JSON-based protocol over TCP sockets:

- **Commands** are sent as JSON objects with a `type` and optional `params`
- **Responses** are JSON objects with a `status` and `result` or `message`

## Limitations & Security Considerations

- The `execute_blender_code` tool allows running arbitrary Python code in Blender, which can be powerful but potentially dangerous. Use with caution in production environments. ALWAYS save your work before using it.
- Poly Haven requires downloading models, textures, and HDRI images. If you do not want to use it, please turn it off in the checkbox in Blender. 
- Complex operations might need to be broken down into smaller steps


#### Telemetry Control

BlenderMCP collects anonymous usage data to help improve the tool. You can control telemetry in two ways:

1. **In Blender**: Go to Edit > Preferences > Add-ons > Blender MCP and uncheck the telemetry consent checkbox
   - With consent (checked): Collects anonymized prompts, code snippets, and screenshots
   - Without consent (unchecked): Only collects minimal anonymous usage data (tool names, success/failure, duration)

2. **Environment Variable**: Completely disable all telemetry by running:
```bash
DISABLE_TELEMETRY=true uvx blender-mcp
```

Or add it to your MCP config:
```json
{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["blender-mcp"],
            "env": {
                "DISABLE_TELEMETRY": "true"
            }
        }
    }
}
```

All telemetry data is fully anonymized and used solely to improve BlenderMCP.


## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Disclaimer

This is a third-party integration and not made by Blender. Made by [Siddharth](https://x.com/sidahuj)
