Connecting the official Blender MCP to Claude Code: from one command to your first scene summary

Based on: Claude Code 2.1.310, Blender 5.2 LTS (screenshots from 5.2.1, English interface, default shortcuts), the Blender Lab MCP server and add-on 1.0.3, and the official Claude Code MCP documentation. Checked in October 2026. All images are real terminal and Blender screens and renders. One line showing a save path in the terminal image is hidden.

Claude Code is an AI assistant that works in the terminal. It reads and writes files, runs commands, and looks at the results. If you attach the official MCP server made by Blender Lab at the Blender Foundation, it can also look directly into the Blender scene you have open. Type "Summarize the open file" in the chat, and Claude Code asks Blender through the MCP tools and answers with a table.

When you finish this guide, you will be able to do the following.

1. Register the official Blender MCP server with the claude mcp add command.
2. Choose a registration scope (local, project, or user).
3. Check the registration status with claude mcp list, claude mcp get, and /mcp.
4. Have Claude Code summarize a Blender file and make a preview render.
5. Know where to fix things when the connection fails or is slow.

If installing Claude Code is new to you, see Getting started with Claude Code first. If installing the add-on on the Blender side is new to you, see Installing the official Blender MCP first. This guide assumes both are done.

1. Two ways to handle Blender with Claude Code

There are two ways Claude Code can drive Blender.

The script way is covered in Connecting Blender and AI and Blender Python automation. This guide is about the MCP way. The official server also has tools that link the two ways. Tools whose names end in _for_cli start a separate Blender without a screen, open a file, and answer. The full tool list is in Trying the 26 tools of the official Blender MCP.

2. What you need

If you do not have uv, paste the official install command into PowerShell. When the installation finishes, close the PowerShell window and open a new one.

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

3. Downloading the server source and installing it in advance

Starting state: start in a new PowerShell window. Git must be installed.

Follow along:

1. Download the source right under the C drive, as in the official wiki (Setup).

cd c:\
git clone https://projects.blender.org/lab/blender_mcp.git

2. Go into the mcp folder inside the downloaded folder and install the parts once.

cd C:\blender_mcp\mcp
uv sync

The downloaded folder is about 23 MB (4,783 files), and about 16 MB of that is the bundled Blender manual and Python API documentation. uv sync installs about 55 MB of parts on top of that. On my PC, uv sync took 57 seconds and reinstalling took 80 seconds.

Do not skip step 2. Claude Code waits for an MCP server to start within a set time. If that time passes while uv is downloading parts on the first run, Claude Code shuts the server down and treats it as a "connection failure." When I skipped this step on my PC and registered right away, Claude Code could not reach the server in the first chat because of a "30-second connection timeout." On top of that, the installation was left half done, so the server also disconnected right away on the next run. If this happens, reinstalling with the command below fixes it.

cd C:\blender_mcp\mcp
uv sync --reinstall

4. The one-line registration command

The official syntax for registering an MCP server in Claude Code is this.

claude mcp add [options] <name> -- <command to run> [arguments for the command...]

The -- (two minus signs) in the middle matters. What comes before -- are options that Claude Code reads, and what comes after -- is passed on as is as the command that starts the server. Without this separation, Claude Code mistakes the server's options for its own. Compared to a parcel, what comes before -- is the shipping label, and what comes after is the item inside the box.

Putting the server command from the official wiki (uv --directory C:\blender_mcp\mcp run blender-mcp) into this syntax gives the following. You choose the scope option (-s) in the next section.

claude mcp add blender-lab -- uv --directory C:\blender_mcp\mcp run blender-mcp

4-1. Choosing a scope

When you register, -s (or --scope) decides where you will use this server.

At first, I recommend making one Blender work folder and registering with the project scope. The tools that drive Blender turn on only in that folder, so Claude Code has no chance to touch Blender while you do other work. It is like putting a lock only on the workshop door, not on the whole house.

4-2. Registering

Starting state: after finishing section 3, start in a new PowerShell window.

Follow along:

1. Make a work folder and go into it (any name works).

mkdir C:\blender-work
cd C:\blender-work

2. Register with the command below. The server name here is blender-lab.

claude mcp add -s project blender-lab -- uv --directory C:\blender_mcp\mcp run blender-mcp

3. Check what you registered.

claude mcp get blender-lab

Figure 1. Registering and checking. Added stdio MCP server blender-lab … below the first line, the scope Project config in the middle, and the status Pending approval below it. On Korean Windows, backslashes appear as ₩. One line with the save path is hidden (PowerShell screenshot)

When you register with the project scope, a .mcp.json file appears in the folder. It contains the following.

{
  "mcpServers": {
    "blender-lab": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "C:\\blender_mcp\\mcp", "run", "blender-mcp"]
    }
  }
}

A status of Pending approval is normal. A settings file inside a folder could have been put there by someone else, so the first time you run Claude Code in that folder, it asks whether it may start this server. You allow it in the next section.

If you want to use it everywhere: register with -s user instead of -s project. In that case you do not need to make a folder, and there is no pending approval.

4-3. A common snag with option order

To pass an environment variable to the server, use -e (or --env). But if you write the server name right after -e, you get an error.

> claude mcp add -s project -e BLENDER_MCP_PORT=9886 blender-lab -- uv ...
Invalid environment variable format: blender-lab, environment variables should be added as: -e KEY1=value1 -e KEY2=value2

This happens because Claude Code read the name as an environment variable too. The official documentation also says to put another option between --env and the server name. Put -e first and -s after it, as below.

claude mcp add -e BLENDER_MCP_PORT=9886 -s project blender-lab -- uv --directory C:\blender_mcp\mcp run blender-mcp

BLENDER_MCP_PORT is the port number the official server uses to call Blender. If you use the default 9876, you do not need it. Match it to the same number only when you have changed the port on the Blender side.

5. Checking the connection

5-1. The first run and approval

Follow along:

1. Start Blender and check Server is running in the MCP add-on.
2. Run claude in the work folder from section 4-2.
3. When a prompt asks whether to use the servers in this folder's .mcp.json, allow blender-lab.
4. Type /mcp in the chat. In the server list, see whether blender-lab is connected. The official server 1.0.3 exposes 26 tools.

In the terminal, you can also check the status with claude mcp list. The list shows every server you have registered. Here is just the Blender line (before approval).

blender-lab: uv --directory C:\blender_mcp\mcp run blender-mcp - ⏸ Pending approval (run `claude` to approve)

What "Connected" means: even when this line changes to ✔ Connected after approval, it means the server program has started. It does not mean it has reached Blender. The official server starts and exposes its 26 tools even when Blender is closed. Only when a tool is actually called does it call Blender. Without Blender, you get an answer like this.

Error executing tool get_blendfile_summary_datablocks: Cannot connect to Blender at localhost:9876. Ensure Blender is running with the MCP addon enabled and the server started.

If you see this message, start Blender and check the server status. The phone line is connected, but nobody is picking up on the other end.

6. Your first chat: summarizing the open file

Starting state: open the official demo file Scattering Pebbles (pebble_scattering.blend, from the blender.org demo files page, CC0) in Blender. Continue in the Claude Code session you opened in section 5-1.

Figure 2. Blender with the demo file open. Claude Code reads the scene in this window through MCP (Blender screenshot)

Follow along:

1. Send the following in the Claude Code chat.

Summarize the Blender file that is open right now. Give the number of objects, materials, and collections, and the render engine, in a short table.

2. When it asks permission to use a tool, see what the tool does and allow it. A read-only summary tool does not change the file.

Here is the answer I actually got. I asked in Korean, so the question above and the answer below are translated into English.

Here is a summary of the Blender file that is open now.

| Item | Value |
|---|---|
| Objects | 12 |
| Materials | 2 |
| Collections | 3 |
| Render engine | Cycles |

- There is one scene, `Scene`.
- Of the 12 objects, 8 are meshes, 1 is a camera, and 3 are lights.
- The workspaces are `General` and `Compositing`, and `General` is open now.

The code execution I tried first was denied, so I looked it up with a summary tool that only reads the file contents. I did not change the file.

Pay attention to the last line. In this chat, only read tools were allowed. Claude Code first tried to use the code execution tool (execute_blender_code), and when it was blocked, it switched to the read-only summary tool (get_blendfile_summary_datablocks) to answer. This shows that the tools you allow decide what the AI can do.

7. Getting a preview render

Next, let's have it make an image. Rendering is Blender calculating the scene and turning it into an image.

Starting state: continue with the same file as in section 6. The demo file's render engine is Cycles. To see results quickly, change Render Engine to EEVEE in the Render tab. The difference between the engines is in EEVEE vs. Cycles.

Follow along:

1. Send the following to Claude Code.

Render the open Blender scene as a small preview image, save it as preview.png, and tell me the path where it was saved.

2. When it asks to use the render tool (render_thumbnail_to_path), allow it.
3. Open the image at the path given in the answer.

Figure 3. The image Claude Code made with the render tool. This is a reduced version of the result, which came out at its original size of 1920×1080 (Blender render, EEVEE)

Two things become clear here. This is the first part of the answer I actually got (translated from Korean).

The preview render worked, but the file was saved in a temporary folder, not the work folder you asked for.

Claude Code does not freely touch files outside the folder it was first opened in. So for moving the image from the temporary folder to the work folder, it asks for your permission or tells you to do it yourself.

8. When the output is long or the server starts slowly

If the text an MCP tool returns is too long, Claude Code warns you. According to the official documentation, it warns when tool output goes over 10,000 tokens and cuts it off at 25,000 tokens by default. A token is the unit AI uses to count text; think of it as a bundle of a few characters. The details are in Tokens and the context window.

In a scene with hundreds of objects, asking "list all the objects" quickly makes the output long. In the official Classroom demo (985 objects), the result of just one object list tool went over 90,000 characters. In that case, narrowing the question comes first.

Practice

1. Run claude mcp get blender-lab in the work folder and write down the Scope and Status lines.
2. With Blender closed, ask Claude Code to "summarize the open file," and see which error message comes back. Then start Blender and ask again.
3. In the Pebble file, ask "list the names of the camera and lights in a table," and compare the answer with the Outliner to see whether it is right.

Common mistakes and fixes

The same name in two scopes is easy to confuse. On my PC, with blender already in the user scope, I registered the same name in the project scope too, and claude mcp get blender showed the user entry. That is why this guide uses a different name, blender-lab.

In one line

Install in advance with uv sync → claude mcp add -s project blender-lab -- uv --directory C:\blender_mcp\mcp run blender-mcp → run claude in the folder and allow it → start with read-only questions. In the next guide, Trying the 26 tools of the official Blender MCP, you call the server's tools one by one.

Read next

• Getting started with Claude Code: from install to your first conversation with an AI coding assistant that works in the terminal
• Installing the official Blender MCP
• Connecting MCP servers: how to plug tools into an AI app
• Trying the 26 tools of the official Blender MCP
• The official Blender MCP vs. the community MCP for Blender
• Connecting Blender and AI: 3D work through MCP and scripts

References

• Claude Code Docs, Connect Claude Code to tools via MCP: https://code.claude.com/docs/en/mcp
• Blender Lab, MCP Server: https://www.blender.org/lab/mcp-server/
• Blender Lab, blender_mcp repository and Setup wiki: https://projects.blender.org/lab/blender_mcp , https://projects.blender.org/lab/blender_mcp/wiki/Setup
• uv installation guide: https://docs.astral.sh/uv/getting-started/installation/
• Blender demo files (Scattering Pebbles, Classroom, CC0): https://www.blender.org/download/demo-files/
• Images: real PowerShell and Blender 5.2.1 screens and a Blender render (EEVEE). The scene is the Blender demo file Scattering Pebbles (CC0)