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 · Installation · Usage · Troubleshooting · Contributing

Full tutorial

Join the Community

Give feedback, get inspired, and build on top of the MCP: Discord

Supporters

Warp, the intelligent terminal for developers

Available for MacOS, Linux, & Windows

Other supporters:

CodeRabbit

Satish Goda

All supporters:

Support this project

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.

Related MCP server: BlenderMCP

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

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

brew install uv

On Windows

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

and then

set Path=C:\Users\nntra\.local\bin;%Path%

Otherwise installation instructions are on their website: Install uv

⚠️ 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:

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:

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:

uv pip install '.[gui]'

Depois, execute:

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

{
    "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 or Open WebUI orchestrates the conversation. A typical setup looks like this:

1. Install Ollama 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:

   {
     "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

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

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

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

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

Cursor setup video

⚠️ 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 installed before proceeding.

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.

2. Open Blender

3. Go to Edit > Preferences > Extensions

4. Click the dropdown menu and choose "Install from Disk..."

5. 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):

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "blender-mcp", "--host", "localhost", "--port", "9876"]
    }
  }
}

LM Studio (mcpServers.json):

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "blender-mcp", "--host", "localhost", "--port", "9876"]
    }
  }
}

Quick diagnostics before connecting:

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

   • 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).

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:

     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

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

• "Create a beach vibe using HDRIs, textures, and models like rocks and vegetation from Poly Haven" Demo

• Give a reference image, and create a Blender scene out of it Demo

• "Get information about the current scene, and make a threejs sketch from it" Demo

• "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

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

   # 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

3. Dependency issues:

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

   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:

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

   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

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:

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

set BLENDER_MCP_UPDATE_BASELINE=1
pytest tests/visual/test_gui_visual_regression.py -q
set BLENDER_MCP_UPDATE_BASELINE=

Enable debug logging

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:

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

2. Join Discord community

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