mcp_blender

# BlenderMCP - Blender Model Context Protocol Integration BlenderMCP connects Blender to local large language models (LLMs) through the Model Context Protocol (MCP), enabling assistants running on your own hardware to automate Blender workflows. This integration provides prompt-assisted 3D modelling, scene creation, and manipulation guided by AI without relying on cloud services. **We have no official website. Any website you see online is unofficial and has no affiliation with this project. Use them at your own risk.** [Quick links](#architecture--data-flow) · [Installation](#installation) · [Usage](#usage) · [Troubleshooting](#troubleshooting) · [Contributing](#contributing) [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 <div align="center" markdown="1"> ^{Special thanks to:} <br> <br> <a href="https://www.warp.dev/blender-mcp"> <img alt="Warp sponsorship" width="400" src="https://github.com/user-attachments/assets/c21102f7-bab9-4344-a731-0cf6b341cab2"> </a> ### [Warp, the intelligent terminal for developers](https://www.warp.dev/blender-mcp) [Available for MacOS, Linux, & Windows](https://www.warp.dev/blender-mcp)<br> </div> <hr> **Other supporters:** [CodeRabbit](https://www.coderabbit.ai/) [Satish Goda](https://github.com/satishgoda) **All supporters:** [Support this project](https://github.com/sponsors/ahujasid) ## Release notes (2.0.0) - **Modular Architecture**: Ported large handlers out of `addon.py` for better stability and maintainability. - **3D Printing Toolkit**: New tools for exact dimensions, print thickness, and automated bed layout. - **Mesh Integrity**: Real-time manifold checking and auto-repair directly through MCP. - **AmbientCG Integration**: Search and download thousands of PBR materials. - **Product Studio**: One-click professional lighting, backdrops, and camera setups for product rendering. - **Vehicle Rigging**: Automated base rigs for chassis and wheels. - **Extension Mode Support**: Fully compatible with Blender 4.2+ Extension system. ## Features - **Professional Asset Sourcing**: Integrated support for Poly Haven, Sketchfab, and AmbientCG. - **Precise 3D Printing**: Exact mm-scale control and automated export workflows. - **Mesh Health**: Integrity checks and automated manifold repairs for 3D printing. - **Studio Automation**: Procedural studio setups, lighting themes, and catalog angle rendering. - **Two-way communication**: Connect local LLM assistants to Blender via socket-based FastMCP. - **Object manipulation**: Create, modify, and delete 3D objects with spatial awareness. - **Material control**: Procedural material node generation and PBR texture application. - **Scene inspection**: Bounding-box aware scene data for collision-free object placement. - **Visual Feedback**: Real-time viewport screenshots for assistant visual grounding. - **Code execution**: Securely controlled Python execution for complex custom tasks. ## Components The system consists of two main components: 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 ## Architecture & Data Flow ```mermaid flowchart LR subgraph MCP Client A[MCP-aware client<br/>(LM Studio, Cursor, Continue)] end subgraph MCP Server B[FastMCP server<br/>(`src/blender_mcp/server.py`)] end subgraph Blender C[Addon socket server<br/>(`addon.py`)] D[bpy / scene graph] end A -- MCP request/response --> B B -- JSON over TCP --> C C -- bpy API --> D D -- results / viewport changes --> A ``` **Interaction summary** - MCP-compatible clients invoke tools exposed by the FastMCP server. The server relays tool calls as JSON commands over TCP to the Blender addon, which executes them on the main Blender thread. - Blender scene changes (object creation, material edits, imports) are driven by the addon’s handlers and returned as structured responses to the MCP client. **Configuration points** - **Socket target**: `BLENDER_HOST` and `BLENDER_PORT` environment variables (defaults `localhost:9876`) configure where the MCP server sends commands. The same values must be used when starting the addon inside Blender. - **Addon panel**: The Blender sidebar exposes toggles such as Poly Haven asset fetching and connection controls (see `addon.py` UI operators). Enabling Poly Haven changes which tools the assistant can call. - **Client launch**: MCP clients should launch the server via `uvx blender-mcp` (see LM Studio/Continue/Cursor sections below). One server instance should be active at a time to avoid port conflicts. For a quick mental model, start at the MCP client, follow the arrows in the diagram, and open the linked source files to see how each hop works. ## Installation ### 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** ```bash powershell -c "irm https://astral.sh/uv/install.ps1 | iex" ``` and then ```bash set Path=C:\Users\nntra\.local\bin;%Path% ``` Otherwise installation instructions are on their website: [Install uv](https://docs.astral.sh/uv/getting-started/installation/) **⚠️ Do not proceed before installing UV** ### 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) You can override these at launch time using CLI flags instead of environment variables: ```bash uvx blender-mcp --host host.docker.internal --port 9876 ``` ### Logging configuration Blender MCP now configures logging from its entrypoint, allowing you to control verbosity and destinations when launching the server from an MCP client: - `BLENDER_MCP_LOG_LEVEL`: Logging level (e.g., `DEBUG`, `INFO`, `WARNING`). - `BLENDER_MCP_LOG_FORMAT`: Standard logging format string (defaults to timestamp/name/level/message). - `BLENDER_MCP_LOG_HANDLER`: `console` (stderr) or `file`. - `BLENDER_MCP_LOG_FILE`: File path when using the `file` handler (default: `blender_mcp.log`). Tool calls now return structured error payloads (`{"error": {"code": "runtime_error", "message": "...", "data": {...}}}`) while detailed diagnostics continue to be written to the configured logs. Example: ```bash export BLENDER_HOST='host.docker.internal' export BLENDER_PORT=9876 uvx blender-mcp --log-level debug --log-format "%(levelname)s:%(message)s" ``` ### Interface gráfica (PySide6) Instale o extra `gui` para habilitar a interface: ```bash uv pip install '.[gui]' ``` Depois, execute: ```bash uv run blender-mcp-gui ``` A janela lista e permite editar todas as variáveis de ambiente usadas pelo servidor (host/porta do Blender e opções de logging), aplicando as mudanças imediatamente e reconfigurando o log sem precisar editar arquivos manualmente. > Dica para Windows/PowerShell: instale o `uv` antes de rodar os comandos acima com `py -m pip install uv` (ou `python -m pip install uv`). Isso coloca o executável `uv.exe` no seu diretório de scripts do Python (geralmente `%APPDATA%\Python\Scripts` ou `%USERPROFILE%\.local\bin`); se o PowerShell não encontrar `uv`, adicione esse caminho à variável de ambiente `PATH`. ### LM Studio integration LM Studio (v0.3.0 or newer) ships with native MCP client support, allowing any locally hosted model to call Blender tools directly. 1. Install [LM Studio](https://lmstudio.ai/) and download the model you want to run locally. 2. Open **Settings → Developer → Model Context Protocol (MCP)**. 3. Click **Add MCP server** and configure it with: - **Command:** `uvx` - **Arguments:** `blender-mcp` 4. Save the configuration and start a chat with your model. A new **Blender MCP** tool tray will appear once the server is running. If you prefer to edit the JSON configuration manually, create or update the LM Studio MCP config file (located at `~/Library/Application Support/LM Studio/mcpServers.json` on macOS, `%APPDATA%/LM Studio/mcpServers.json` on Windows, or `~/.config/LM Studio/mcpServers.json` on Linux) with: ```json { "mcpServers": { "blender": { "command": "uvx", "args": ["blender-mcp"], "env": {} } } } ``` Restart LM Studio after saving to load the server definition. ### Ollama integration Ollama provides the model runtime, while an MCP-aware client such as [Continue](https://continue.dev/) or [Open WebUI](https://github.com/open-webui/open-webui) orchestrates the conversation. A typical setup looks like this: 1. Install [Ollama](https://ollama.com/) and run `ollama pull llama3` (or any other model you prefer). 2. Install the Continue extension for VS Code or the Continue desktop client and choose **Ollama** as the provider for your assistant. 3. In Continue’s settings (`continue.json`), register the Blender MCP server: ```jsonc { "mcpServers": { "blender": { "command": "uvx", "args": ["blender-mcp"] } } } ``` 4. Start the Continue session, ensure Ollama is running, and request the assistant to use the Blender MCP tools. You can reuse the same configuration with any MCP-compatible client that proxies queries to Ollama. ### Cursor integration [](https://cursor.com/install-mcp?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 at a time within your chosen MCP client** ### Visual Studio Code Integration _Prerequisites_: Make sure you have [Visual Studio Code](https://code.visualstudio.com/) installed before proceeding. [](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) ### Installing the Blender Extension 1. In GitHub Releases, download the Blender extension asset (for example: `blender-mcp-extension-v1.3.1.zip`). Do not use the automatic "Source code (zip)" file. 1. Open Blender 2. Go to Edit > Preferences > Extensions 3. Click the dropdown menu and choose "Install from Disk..." 4. Select the extension `.zip` and enable "Blender MCP" The extension package includes `blender_manifest.toml` and `__init__.py` at zip root, as required by Blender Extensions. ## Usage ### Starting the Connection  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 LLM client" 5. Ensure your MCP client has started the `blender-mcp` server (you can also launch it manually with `uvx blender-mcp` if needed) You can also use the new **Local Setup** buttons in the BlenderMCP panel: - **Check/Install Dependencies**: runs `uv sync --extra gui --extra test` in the project root. - **Run MCP Server in Terminal**: launches `uv run blender-mcp --host localhost --port <panel-port>` in a new terminal. - **Copy MCP Client Config**: copies a ready stdio config snippet (Claude Desktop, Cursor, Ollama-compatible MCP client, LM Studio) to your clipboard. - **Health Check**: runs `uv run blender-mcp --doctor --host localhost --port <panel-port>` and prints diagnostics in Blender console. - **Open Logs**: opens the active `blender_mcp.log` file (or `BLENDER_MCP_LOG_FILE`) in the OS default app. ### MCP config snippets (Claude Desktop + LM Studio) Use these snippets when configuring MCP over `stdio`. Replace `localhost` and `9876` if your Blender addon is listening elsewhere. Claude Desktop (`claude_desktop_config.json`): ```json { "mcpServers": { "blender": { "command": "uv", "args": ["run", "blender-mcp", "--host", "localhost", "--port", "9876"] } } } ``` LM Studio (`mcpServers.json`): ```json { "mcpServers": { "blender": { "command": "uv", "args": ["run", "blender-mcp", "--host", "localhost", "--port", "9876"] } } } ``` Quick diagnostics before connecting: ```bash uv run blender-mcp --doctor --host localhost --port 9876 ``` ### Complete usage walkthrough Use the steps below the first time you bring everything online or when you are troubleshooting a broken setup. The goal is to ensure Blender, the MCP server, and your chosen client are all pointing at each other correctly. 1. **Prep Blender and the addon** - Install and enable Blender MCP (see [Installing the Blender Extension](#installing-the-blender-extension)). - Open the **BlenderMCP** tab in the sidebar and keep the panel visible so you can read connection status updates. 2. **Verify host/port alignment** - In the Blender panel, check the host and port fields. They default to `localhost` and `9876`. - If you need Blender to accept connections from another machine or container, set matching values via the environment variables `BLENDER_HOST` and `BLENDER_PORT` before starting the MCP server (see [Environment Variables](#environment-variables)). 3. **Start the MCP server** - Let your MCP-aware client (LM Studio, Continue, Cursor, VS Code, etc.) launch the server automatically **or** start it yourself in a terminal with: ```bash uvx blender-mcp ``` - Keep the terminal window open; the server logs will report connection attempts and tool calls. 4. **Connect from Blender** - In Blender, click **Connect to LLM client**. The status message in the panel should change to connected after a few seconds. - If it fails, confirm no other `blender-mcp` server instance is already running and that firewalls allow TCP on the chosen port. 5. **Test round-trip communication** - In your MCP client, ask the assistant to “list all objects in the scene.” - Blender should respond with object data in the chat, confirming the end-to-end path: MCP client → MCP server → Blender addon → back to client. 6. **Stay within one running server** - Only one MCP server instance should be active per machine. If you switch clients, stop the previous server first to avoid port conflicts. ### Practical tips for day-to-day use - **Keep Blender open**: The addon processes commands on Blender’s main thread, so the Blender window must remain open while you work. - **Save often**: Tool calls can perform destructive actions (e.g., mass delete). Save versions or enable auto-save to protect work in progress. - **Prefer small, explicit requests**: Break complex prompts into steps like “create room layout” → “add lighting” → “apply materials” to get predictable results. - **Inspect tool calls**: Most MCP clients show a tool-call log. Use it to understand what the assistant is sending to Blender and to copy/adjust commands. - **Run from scripts**: You can invoke `uvx blender-mcp` from your own automation (shell scripts, Makefiles, CI) as long as Blender is running with the addon enabled. ### Using with local LLM clients Once your MCP client (LM Studio, Continue, Cursor, etc.) is configured and the addon is running inside Blender, the assistant will expose a hammer icon with the Blender MCP tools.  #### 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/) ### Example Commands Here are some examples of what you can ask your local assistant 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) - "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" ### Security Note ```bash # Linux/Mac # Windows PowerShell # Windows CMD ``` If not set, the addon will not auto-fill a free trial key. ## Troubleshooting ### Common Issues and Solutions #### Connection refused / Cannot connect to Blender **Symptoms**: Error messages like "Connection refused", "No connection could be made", or timeout errors. **Solutions**: 1. **Verify addon is running**: - Open Blender - Go to 3D View sidebar (press `N`) - Find the "BlenderMCP" tab - Check that the status shows "Connected" or "Server running" - If not, click "Connect to LLM client" 2. **Check port and host match**: - Addon uses `localhost:9876` by default - Check environment variables `BLENDER_HOST` and `BLENDER_PORT` - Ensure MCP server config matches addon settings 3. **Firewall blocking**: - Check if firewall is blocking port 9876 - On Linux: `sudo ufw allow 9876/tcp` - On Windows: Add exception in Windows Defender Firewall - On Mac: System Preferences > Security & Privacy > Firewall > Firewall Options 4. **Port already in use**: - Only one MCP server instance should run at a time - Kill any existing processes: `lsof -ti:9876 | xargs kill -9` (Linux/Mac) - On Windows: `netstat -ano | findstr :9876` then task kill #### MCP server not starting **Symptoms**: `uvx blender-mcp` fails or MCP client shows server not available. **Solutions**: 1. **uv not installed**: ```bash # Mac brew install uv # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" set Path=C:\Users\<username>\.local\bin;%Path% # Linux curl -LsSf https://astral.sh/uv/install.sh | sh ``` 2. **Python version mismatch**: - Requires Python 3.10+ - Check: `python --version` - Install from [python.org](https://www.python.org/downloads/) 3. **Dependency issues**: ```bash # Force reinstall uvx --force blender-mcp ``` #### Timeout errors / "Blender did not respond" **Symptoms**: Operations timeout, incomplete responses, or "Blender did not respond after N attempts". **Solutions**: 1. **Increase timeout values**: ```bash export BLENDER_SOCKET_TIMEOUT=30 export BLENDER_CONNECT_ATTEMPTS=5 export BLENDER_COMMAND_ATTEMPTS=5 ``` 2. **Complex operations**: - Break requests into smaller steps - For Poly Haven/Sketchfab downloads, larger files need more time 3. **Blender is busy**: - Ensure Blender window is responsive - Close other heavy Blender operations - Save your work before large operations #### PolyHaven integration not working **Symptoms**: "PolyHaven integration is disabled" or assets not downloading. **Solutions**: 1. **Enable in Blender**: - Open BlenderMCP tab in sidebar - Check the "Poly Haven" checkbox - Status should show "enabled" 2. **Network issues**: - Check internet connection - Verify access to https://api.polyhaven.com - Check proxy settings if behind corporate firewall 3. **Remind the assistant**: - Sometimes AI forgets - Tell it: "Check PolyHaven status first" or "Enable PolyHaven checkbox in Blender" **Symptoms**: "Insufficient balance", generation errors, or timeout during generation. **Solutions**: 1. **Free trial limits**: - Free trial key has daily limits - If exceeded, you must: - Wait for next day (resets at midnight UTC) 2. **Check API mode**: - Addon supports two modes: MAIN_SITE and FAL_AI - Check which is configured in Blender - Use appropriate parameters (paths vs URLs for images) 3. **Polling vs waiting**: - Don't wait synchronously for generation - Create job → Poll status → Import when complete - Generation can take several minutes #### Import errors / Module not found **Symptoms**: `ImportError`, `ModuleNotFoundError`, or missing dependencies. **Solutions**: 1. **Install with extras**: ```bash # For GUI uvx blender-mcp --with PySide6 # Or install in venv uv pip install 'blender-mcp[gui]' ``` 2. **Check Python path**: - Ensure `uvx` is using correct Python - Check: `uvx --python 3.11 blender-mcp` 3. **Reinstall clean**: ```bash uv cache clean uvx --force --reinstall blender-mcp ``` #### Platform-specific issues **Windows**: - PowerShell execution policy: `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned` - Path separators: Use forward slashes `/` or escaped backslashes `\\` - Long paths: Enable [long path support](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation) **Mac**: - Gatekeeper blocking: Right-click > Open for first run - Permissions: Grant Blender network permissions when prompted - Apple Silicon: Ensure ARM64 Python version **Linux**: - AppImage Blender: May have isolated environment - Snap Blender: Check confinement permissions - Flatpak Blender: Use `--socket` permissions ### Advanced Troubleshooting #### Validation smoke tests Use these commands to validate the critical path incrementally: ```bash # Real Blender + addon socket smoke test (Windows default path: C:\Blender\blender.exe) pytest tests/test_e2e_addon_server.py -q # MCP server diagnostics unit tests pytest tests/test_server.py -q # GUI validation tests (requires PySide6) pytest tests/test_gui.py -q # Visual regression (requires PySide6 + baseline image) pytest tests/visual/test_gui_visual_regression.py -q ``` To create/update visual baseline intentionally: ```bash set BLENDER_MCP_UPDATE_BASELINE=1 pytest tests/visual/test_gui_visual_regression.py -q set BLENDER_MCP_UPDATE_BASELINE= ``` #### Enable debug logging ```bash export BLENDER_MCP_LOG_LEVEL=DEBUG export BLENDER_MCP_LOG_HANDLER=file uvx blender-mcp ``` Check `blender_mcp.log` for detailed diagnostics. #### Test connection manually Start a mock server to test connectivity: ```python import socket, json sock = socket.socket() sock.bind(('localhost', 9876)) sock.listen(1) print("Listening on localhost:9876") conn, addr = sock.accept() print(f"Connected: {addr}") while True: data = conn.recv(8192) if not data: break print(f"Received: {data.decode()}") response = json.dumps({"status": "ok", "result": {}}) conn.sendall(response.encode()) ``` Then test from MCP client. #### Check addon console In Blender: - Window > Toggle System Console (Windows) - View console output for error messages - Check for socket binding errors or exceptions ### Getting Help If issues persist: 1. Check [GitHub Issues](https://github.com/modelcontextprotocol/blender-mcp/issues) 2. Join [Discord community](https://discord.gg/z5apgR8TFU) 3. Include in bug report: - Operating system and version - Blender version - Python version - Full error message - Steps to reproduce - Logs (with `--log-level DEBUG`) ### Known Limitations - **Connection issues**: First command sometimes fails, subsequent ones work - **Complex operations**: May need to be broken into smaller steps - **Poly Haven**: Requires enabled checkbox; assistant may forget - **execute_blender_code**: Powerful but dangerous - always save first - **Screenshot quality**: Limited by viewport size and settings ## 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 ## 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)