← All guides AI Release RU Subscribe to @ai_release1

How to Connect an AI Assistant to Blender via MCP: BlenderMCP Setup Guide

Updated: 13.11.2026 · AI Release · @ai_release1

TL;DR

Time to complete: 20–30 minutes
Difficulty: Intermediate (you edit one JSON config file and restart an app)
You will need: Blender (3.x or newer — confirm the exact minimum in the project README), Python 3.10+, uv/uvx (the runner that launches the MCP server), the BlenderMCP add-on file addon.py, and an MCP-capable AI client (Claude Desktop is the reference client). An AI client subscription or API key is required — the Blender side is free.
Result: you type a request in plain language in the chat client, and Blender creates or edits objects in your open scene.

MCP (Model Context Protocol) is an open standard that lets an AI app call external tools — here, the "tool" is a socket server running inside Blender.

Requirements and setup

OS: macOS, Windows or Linux with a desktop session. Blender must run in the GUI, not headless — the add-on lives in the 3D Viewport sidebar.
Blender: installed and able to open a default scene. The exact minimum version is stated in the BlenderMCP README — check it before installing, and note your version at *Help → About Blender*.
Package runner: uv from Astral. It provides uvx, which downloads and runs the MCP server without a manual virtualenv.
AI client: Claude Desktop (or another client that supports MCP servers). If you prefer to route a cloud model through your own cloud project instead of a desktop subscription, see How to Access OpenAI Models via Google Cloud — the MCP config block stays the same, only the model endpoint changes.
Disk space: a few hundred MB for uv caches plus the BlenderMCP package.
Rights: permission to write into your user config folder and to install Blender add-ons.
A local fallback: if you want no cloud calls at all, an OpenAI-compatible local server works with the same client. The wiring is described in How to connect n8n to a local LLM with Ollama.

Install uv with pip if you already have Python on PATH:

python -m pip install --upgrade uv

Example: on macOS/Linux confirm the binary location with which uvx → /Users/<you>/.local/bin/uvx. On Windows run where uvx in PowerShell → C:\Users\<you>\.local\bin\uvx.exe. Keep this path; you will paste it into the client config in Step 2.

Step 1. Install the BlenderMCP add-on and open the socket server

What to do: get the BlenderMCP repository, locate addon.py, then in Blender open *Edit → Preferences → Add-ons → Install…* (in Blender 4.x the button is labeled *Install from Disk*), select addon.py, and tick the checkbox next to "BlenderMCP" in the add-ons list. Press N in the 3D Viewport to open the sidebar and click the BlenderMCP tab.

Why: the add-on starts a local socket server inside Blender. The MCP server process (Step 2) talks to that socket, so every AI request ultimately becomes Python executed in your Blender session. Nothing leaves your machine through this socket — the model only sees the data the server sends it.

How to check: the sidebar panel shows a Connect to MCP server button, a port field, and a status line. The default port is 9876 — if your panel shows a different number, note it, because the server and the add-on must agree. Click Connect to MCP server; the status line switches to a connected state. If the tab is missing after installing, the add-on checkbox is off or Blender needs a restart.

Example: with the panel open and the server not yet started, clicking Connect produces a connection error — that is expected at this stage. The panel is the control surface you will come back to.

Step 2. Start the MCP server and register it in the AI client

What to do: you do not start the server by hand — the AI client launches it. Open the client's config file and add a blender entry.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

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

If the client cannot find uvx (typical on Windows, because GUI apps do not inherit your shell PATH), replace command with the absolute path from Step 1:

{
  "mcpServers": {
    "blender": {
      "command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe",
      "args": ["blender-mcp"]
    }
  }
}

Fully quit and reopen the client — a window reload is not enough, the config is read at startup.

Why: uvx blender-mcp downloads the server package into an isolated environment and runs it, so the client gets a stdio process it can send tool calls to. The server then forwards scene queries and execute_blender_code calls to the add-on's socket on port 9876.

How to check: in the client, open the tools/connectors menu — blender appears in the server list with a set of tools such as scene info, object info, code execution and a viewport screenshot. Then go back to Blender, click Connect to MCP server in the sidebar, and confirm the panel reports a connection. Two green states (client sees the server, add-on sees the connection) are the real success signal.

Example: with both sides up, ask in the chat: *"Use Blender to tell me what objects are in the current scene."* The answer lists the default Cube, Camera and Light — proof the round trip works before you change anything.

Step 3. Run your first tasks and verify the result

What to do: work in small, single-purpose requests and verify each one inside Blender before asking for the next. Start read-only, then move to creation.

1. *Read:* "List all objects in the scene with their types and locations." → expect a table of Cube, Camera, Light.

2. *Create:* "Add a cube named Test_Cube at (2, 0, 0), 1 m per side." → expect a new object in the Outliner.

3. *Inspect:* "Get the dimensions of Test_Cube." → expect three values of 1.

4. *Visual check:* "Take a viewport screenshot." → expect an image of your viewport in the chat, which is how you catch a model that reports success while nothing changed.

Why: every action is real Python in your file. Read-only calls first prove the transport, and a screenshot proves the scene actually changed rather than the model only claiming it did.

How to check: open Blender's Python Console (*Scripting* workspace → *Console*) and run:

import bpy
print([(o.name, o.type) for o in bpy.data.objects])

Expected output for the example above:

[('Cube', 'MESH'), ('Camera', 'CAMERA'), ('Light', 'LIGHT'), ('Test_Cube', 'MESH')]

Checklist before you move on to real work:

[ ] The BlenderMCP tab reports a live connection.
[ ] The client lists the blender server's tools.
[ ] A read-only request returns your actual scene contents.
[ ] A creation request produces an object visible in the Outliner.
[ ] A viewport screenshot comes back in the chat.
[ ] You saved the scene with Ctrl+S under a new filename before experimenting further.

Example: ask "Add a subdivided plane and set its scale to (10, 10, 1)". After the call, bpy.data.objects['Plane'].scale in the console should read Vector((10.0, 10.0, 1.0)). If it still reads (1,1,1), the code ran but targeted the wrong object — inspect the object name the model used.

Troubleshooting

Problem. The client shows the server but every Blender call fails with a connection error

Error: Connection refused in the add-on panel, or a tool result stating the add-on is not connected.
Cause: the add-on's socket server is not listening — the Connect to MCP server button was never pressed, Blender was restarted, or the port in the panel differs from the one the server expects.
Solution: press Connect to MCP server in the BlenderMCP sidebar, confirm the port field shows 9876, then retry the request. If the panel still refuses, check that no other process holds the port: lsof -i :9876 on macOS/Linux, netstat -ano | findstr :9876 on Windows.

Problem. Claude Desktop starts but no blender tools appear

Error: spawn uvx ENOENT in the client's MCP log for the blender server.
Cause: the client is a GUI app and does not inherit the shell PATH, so uvx cannot be resolved. Same failure appears if uv was installed after the client was last started.
Solution: replace "command": "uvx" with the absolute path from which uvx / where uvx, escape backslashes on Windows (C:\\Users\\...\\uvx.exe), then fully quit and reopen the client. Verify the path first: uvx --version must print a version in your terminal.

Problem. Requests return a Python traceback instead of an object

Error: a Blender-side NameError: name 'bpy' is not defined or AttributeError returned in the chat.
Cause: the model generated code without the import bpy line, or referenced API that changed between Blender versions.
Solution: reply "import bpy first, then retry" and repeat the request in one sentence; if the error names an API attribute, ask the model to check the current Blender Python API for your version — blender-mcp executes raw code, so API drift is your responsibility, not the transport's.

Summary and next steps

You now have a working loop: an AI client, an MCP server launched by uvx blender-mcp, and a Blender add-on listening on port 9876. Next, save a copy of a real project, ask the assistant to describe its scene graph before changing anything, and only then let it modify geometry.

FAQ

Do I need to keep a terminal window open?

No. The AI client spawns uvx blender-mcp itself from its config file. You only need Blender running with the add-on connected.

Does this send my .blend file to the model?

No. The add-on exposes a local socket; the server sends only the scene data and results the model asks for. Be aware that object names, dimensions and code snippets do travel to the model provider, and screenshots are sent when you request them.

Which AI clients work besides Claude Desktop?

Any client that supports MCP servers with a stdio transport and a JSON config. The config block is the same shape; only the file location and the restart procedure differ — verify them in your client's documentation.

Can it download materials and models for me?

BlenderMCP ships integrations for external asset sources; which ones are enabled depends on your add-on version and their API keys. Open the BlenderMCP panel and the README to see the current list — do not assume a provider is available.

🤖 AI summary

AI Release Knowledge Layer
Machine-readable description · Version 1.0

Status: practical guide. Some statements come from vendors; verify in your environment.

1. Summary

Time to complete: 20–30 minutes Difficulty: Intermediate (you edit one JSON config file and restart an app)

Inside: direct answers, key facts, entities, context, reliability, unknowns and sources.

Machine data: Citation Map JSON · JSON-LD · Semantic Embeddings — separate stage.

Full Knowledge Layer: sections 2–8

2. Direct answers

What is required?: OS: macOS, Windows or Linux with a desktop session. Blender must run in the GUI, not headless — the add-on lives in the 3D Viewport sidebar.; Blender: installed and able to open a default scene. The exact minimum version is stated in the BlenderMCP README — check it before installing, and note your version at *Help →… → details (AR-GUIDE-KAKPODKLYU-003)
How to do it?: Step 1. Install the BlenderMCP add-on and open the socket server → Step 2. Start the MCP server and register it in the AI client → Step 3. Run your first tasks and verify the result → details (AR-GUIDE-KAKPODKLYU-004)
Which topics does it cover?: blender mcp как установить, blendermcp аддон настройка, ии ассистент для blender, mcp сервер blender, blender ai плагин claude → details (AR-GUIDE-KAKPODKLYU-002)
What are the key points?: Time to complete: 20–30 minutes Difficulty: Intermediate (you edit one JSON config file and restart an app) → details (AR-GUIDE-KAKPODKLYU-007)

3. Key facts

Time to complete: 20–30 minutes — evidence; status: заявление источника.
Difficulty: Intermediate (you edit one JSON config file and restart an app) — evidence; status: заявление источника.
You will need: Blender (3.x or newer — confirm the exact minimum in the project README), Python 3.10+, uv/uvx (the runner that launches the MCP server), the BlenderMCP add-on file addon.py, and an MCP-capable AI client (Claude Desktop is the reference client). An AI client subscription or API key is required — the Blender side is free. — evidence; status: заявление источника.
Result: you type a request in plain language in the chat client, and Blender creates or edits objects in your open scene. — evidence; status: заявление источника.
OS: macOS, Windows or Linux with a desktop session. Blender must run in the GUI, not headless — the add-on lives in the 3D Viewport sidebar. — evidence; status: заявление источника.
Blender: installed and able to open a default scene. The exact minimum version is stated in the BlenderMCP README — check it before installing, and note your version at *Help → About Blender*. — evidence; status: заявление источника.
Package runner: uv from Astral. It provides uvx, which downloads and runs the MCP server without a manual virtualenv. — evidence; status: заявление источника.

4. Entities

Entity	Type	Role
blender mcp как установить	тема/инструмент	упоминается в заголовке, TL;DR или разделах гайда
blendermcp аддон настройка	тема/инструмент	упоминается в заголовке, TL;DR или разделах гайда
ии ассистент для blender	тема/инструмент	упоминается в заголовке, TL;DR или разделах гайда
mcp сервер blender	тема/инструмент	упоминается в заголовке, TL;DR или разделах гайда
blender ai плагин claude	тема/инструмент	упоминается в заголовке, TL;DR или разделах гайда
Windows	платформа/технология	упоминается в заголовке, TL;DR или разделах гайда
Linux	платформа/технология	упоминается в заголовке, TL;DR или разделах гайда
macOS	платформа/технология	упоминается в заголовке, TL;DR или разделах гайда
Python	платформа/технология	упоминается в заголовке, TL;DR или разделах гайда
OpenAI	компания	упоминается в заголовке, TL;DR или разделах гайда

5. Context

Guide — describes → How to Connect an AI Assistant to Blender via MCP: BlenderMCP Setup Guide (AR-GUIDE-KAKPODKLYU-001).
Guide — includes step → Step 1. Install the BlenderMCP add-on and open the socket server (AR-GUIDE-KAKPODKLYU-001).

6. Reliability

Confirmed

No independent confirmation is provided; source claims and editorial conclusions are separated below.

Source claims

Product features, versions, prices and limits come from vendors and the guide.
Commands and steps are recommendations, not guaranteed results.

AI Release analysis

Structure, comparison and selection criteria are editorial.
The guide does not replace an independent audit or legal advice.

7. Unknowns

Current versions, prices and limits.
Independent benchmarks and quality checks.
Terms of use and data policy.

8. Sources

Source	Type	Role
No external links	—	—

Cite as: AI Release. Как подключить ИИ-ассистента к Blender через MCP: установка BlenderMCP и первые задачи. ai-release.org.