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

> AI Release · @ai_release1 · https://ai-release.org/guides/kak-podklyuchit-ii-assistenta-k-blender-cherez-mcp-usta_en.html

## 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
![Illustration: Requirements and setup](https://ai-release.org/guides/img/kak-podklyuchit-ii-assistenta-k-blender-cherez-mcp-usta-en-1.jpg?v=1794559098)

- **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](https://ai-release.org/guides/kak-podklyuchit-modeli-openai-cherez-google-cloud-posha.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide) — 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](https://ai-release.org/guides/kak-podklyuchit-n8n-k-lokalnoy-yazykovoy-modeli-poshago.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

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

```bash
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
![Illustration: Step 2. Start the MCP server and register it in the AI client](https://ai-release.org/guides/img/kak-podklyuchit-ii-assistenta-k-blender-cherez-mcp-usta-en-2.jpg?v=1794559111)

**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`

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

```json
{
  "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
![Illustration: Step 3. Run your first tasks and verify the result](https://ai-release.org/guides/img/kak-podklyuchit-ii-assistenta-k-blender-cherez-mcp-usta-en-3.jpg?v=1794559123)

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

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

Expected output for the example above:

```text
[('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.