When Blender MCP won't connect: checking the add-on, port, timeout, and uv in order

Based on: Blender 5.2 LTS (screenshots from 5.2.1, English UI), Blender Lab MCP add-on and server 1.0.3, Claude Code 2.1.318 and its official MCP docs, Windows 11 PowerShell. Checked in November 2026. All figures are real Blender and PowerShell screens.

Blender MCP is a path with three links. The AI app starts the server, the server calls the add-on inside Blender, and the add-on does the work in Blender. When nothing connects, first find which of the three links is broken. It is like checking for water: the tap in the house, the meter, then the pipe outside.

This guide checks one link at a time, from the Blender side out to the AI app. Each link comes with a real error screen and the fixed screen.

After this guide you will be able to:

1. Read the add-on's status line and confirm the server is on. (Section 2)
2. Check with one PowerShell line that Blender's port is open. (Section 3)
3. Read the server status in the AI app and fix a timeout. (Sections 4–5)
4. Check that uv exists and measure how long the server takes to start. (Section 6)
5. Read the error text returned to the AI and tell which link failed. (Section 7)

If you have not installed it yet, follow Installing the official Blender MCP first.

1. The checking order at a glance

If one step is not fine, skip the later ones. If you are stuck at step 1, fix step 1 and try again.

2. Inside Blender: the add-on status line

Starting point: Blender is open. Any file will do.

Steps:

1. Open Edit > Preferences.
2. Click Add-ons on the left.
3. Type mcp in the search box at the top.
4. Click the arrow on the left of the MCP row to expand it.
5. Read the status line at the bottom.

The status line shows one of three things.

Figure 1. The server is stopped. The Start MCP Bridge Server button and the Server is stopped line at the bottom, Port 9876 in the middle. The Missing Add-ons row at the top of the figure does not affect MCP and may not appear on your screen (Blender screenshot)

With Auto Start on, the server starts by itself one second after Blender opens. If it still says Server is stopped, it tried and failed. A failure adds one more warning line under the status line.

The most common warning appears when online access is turned off.

Figure 2. The MCP add-on in a Blender with online access off. The warning "Online access must be enabled in the system preferences" under Server is stopped (Blender screenshot)

The add-on only uses connections inside your own PC, not the internet. Even so, Blender's rules require the online access setting to be on before the server starts.

Steps (when you see the warning in Figure 2):

1. Click System on the left of Preferences.
2. Turn on Allow Online Access in the Network group.
3. Go back to Add-ons > MCP and click Start MCP Bridge Server.
4. Check that the status line changes to Server is running.

You get the same warning if Blender was started with --offline-mode from a shortcut or command. Remove that option from the shortcut's Target box.

If the add-on is not in the list at all, check your Blender version first. The official add-on only installs on Blender 5.1 or later (Help > About shows the version).

3. Blender's port: one PowerShell line

Starting point: continue after seeing Server is running in Section 2.

Even when the add-on says it is running, you can check that it really answers on its number (port). Think of a port as an extension number inside your PC. The official add-on's default port is 9876.

Steps:

1. Open PowerShell from the Start menu.
2. Type the command below and press Enter.

Test-NetConnection 127.0.0.1 -Port 9876 -InformationLevel Quiet

3. If the last line is True, Blender is answering on that port. If it is False, nothing is answering.

Figure 3. Port check results. The figure compares a Blender started on port 9877 (True) with an empty port 9878 (False); the warning prefix and AM/PM marks are in Korean (terminal screenshot)

127.0.0.1 means "this PC itself". You can type localhost instead, but it tries the IPv6 address first and may print an extra warning. Only the last line matters.

How to change ports, and how to fix a clash with the community MCP, is in the port section of the official vs. community comparison. If you change the port, tell the server on the AI app side as well. The official server reads the port from an environment variable named BLENDER_MCP_PORT.

Get-Process blender-mcp at the bottom of Figure 3 lists the MCP server programs running right now. Each AI app starts its own server when a conversation begins, so you may see several. Even with several left over, as in Figure 3, new connections still work. To clean up, close all AI apps and restart the computer.

4. The AI app side: reading the server status

Starting point: continue after seeing True in Section 3. This section uses Claude Code. For other apps, see the table at the end.

Steps:

1. Type the command below in PowerShell. Replace blender with the server name you registered.

claude mcp get blender

2. Read the Status: line.

Good to know: Connected only means the link between the AI app and the server works. The server calls Blender only when the AI actually uses a tool. So you can see Connected even when Blender is closed. That is why Sections 2 and 3 come first.

Where other apps show server status:

5. Timeouts: when the server starts slowly

Starting point: continue when Section 4 showed Failed to connect with "timed out".

An AI app waits for the MCP server to start only for a set time. In Claude Code the default is 30 seconds (MCP_TIMEOUT in the official docs). If the server starts later than that, the app treats it as a failed connection. It is like a restaurant that cancels your booking when no table is free within 30 minutes.

Figure 4 shows the same error on purpose. With the wait set to 5 seconds it failed; with 90 seconds it connected.

Figure 4. Results with different wait times. At 5 seconds, Failed to connect and timed out after 5000ms on the Issue line; at 90 seconds, Connected (terminal screenshot)

Steps (raising the wait time in Claude Code):

1. Run this line in PowerShell first. The number is in milliseconds; 90000 is 90 seconds.

$env:MCP_TIMEOUT = "90000"

2. Run claude in the same window.
3. In the chat, check with /mcp that the Blender server is connected.

This setting only lasts in that PowerShell window. Set it again in a new window.

Other apps have a wait-time setting too, with different names and defaults.

Codex has the shortest default, 10 seconds. On a PC where the server takes 16 to 26 seconds to start, as in Section 6, Claude Code may connect while only Codex fails. If you use Codex, add one line, startup_timeout_sec = 30, under the Blender server entry in config.toml (a line such as [mcp_servers.blender]) to raise it to 30 seconds.

Before raising the time, measure in Section 6 why the server is slow.

6. Checking uv and timing the server start

Starting point: continue in the same PowerShell window as Section 5.

The official server usually starts through a tool called uv. uv runs a Python program together with the parts it needs, like a kitchen helper who fetches the ingredients and serves the dish. If uv is missing or cannot be found, the server never starts.

Steps:

1. Find where uv is.

where.exe uv
uv --version

2. If you see a path and a version number, uv is there. If it says it cannot be found, install uv and open a new PowerShell window. The install command is in Section 5 of Installing the official Blender MCP.
3. Measure how long the server takes to start. Change the folder path to where you downloaded the server.

Measure-Command { uv --directory C:\blender_mcp\mcp run blender-mcp --help } | Select-Object TotalSeconds

Figure 5. uv's location and version, and the server start time. TotalSeconds 24.0 at the bottom is how many seconds the server took to show its help once. The figure shows a server downloaded under the user folder (terminal screenshot)

--help starts the server, shows its usage, and exits. So this time is close to "how long the server takes to start". On my PC the same measurement varied between 16 and 26 seconds. That is quite close to Claude Code's default wait of 30 seconds. In fact, on my PC the Blender server once failed to connect with "connection timed out after 30000ms" when Claude Code started.

Why the first run is slow, and how to pre-install with uv sync, is in Section 3 of Adding the official Blender MCP to Claude Code.

7. Reading the error text in the AI's answer

If Sections 1–6 are all fine and the AI still could not do the job, look at the error text in its answer. The official server returns fixed sentences, so it is easy to tell which link failed.

Below is the tool result we got after pointing the server at a port Blender was not answering on and asking "Tell me which objects are in the open Blender scene."

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

With this result the AI answered that it could not connect to Blender and could not get the list, then asked us to check that Blender was open and the add-on server was started.

The last row is a bit special. The official server also has tools that start Blender separately without a window to read a file, instead of using the open Blender (their names end in _for_cli). These tools look for the Blender program in an environment variable named BLENDER_PATH, or else by the name blender. On Windows that name usually is not found, so you get this error. If you want the AI to work in your open Blender, just tell it "do it in the open Blender".

The add-on handles requests when Blender is idle. While a render is running or a file dialog is open, requests wait. So if you start a heavy render and ask for something else, the answer comes late.

Practice

1. Write down the status line from Section 2 and the port check from Section 3. Check that they agree (running means True).
2. Close Blender and run the command from Section 3 to see False. Then open Blender, run it again, and check that it becomes True.
3. Run Measure-Command from Section 6 three times and write down the times. Check that the longest is shorter than your AI app's wait time.

Common mistakes and fixes

In one line

Blender status line (running) → port check (True) → app server status (Connected) → server start time vs. wait time → error text, one link at a time from the front. Once connected, give it a first job with Ten first prompts for Blender MCP.

Read next

• Installing the official Blender MCP
• Adding the official Blender MCP to Claude Code
• The official Blender MCP vs. the community MCP for Blender
• Safety check before handing Blender to AI
• Connecting MCP servers
• Ten first prompts for Blender MCP
• Choosing an AI tool for Blender MCP

References

• Blender Lab, MCP Server: https://www.blender.org/lab/mcp-server/
• Blender Lab, blender_mcp repository: https://projects.blender.org/lab/blender_mcp
• Claude Code MCP docs (server status, timeouts): https://code.claude.com/docs/en/mcp
• Claude Code environment variables (MCP_TIMEOUT): https://code.claude.com/docs/en/env-vars
• Blender 5.2 Manual, System preferences (online access): https://docs.blender.org/manual/en/5.2/editors/preferences/system.html
• Blender 5.2 Manual, command line arguments (--offline-mode): https://docs.blender.org/manual/en/5.2/advanced/command_line/arguments.html
• Microsoft, Test-NetConnection: https://learn.microsoft.com/powershell/module/nettcpip/test-netconnection
• uv installation: https://docs.astral.sh/uv/getting-started/installation/
• Figures: all real Blender 5.2.1 screens and Windows PowerShell screens