Requests hang indefinitely on Windows: server accepts the connection on :9876 but never returns a response
Summary
On Windows, blender-mcp reaches a state where the TCP server inside Blender accepts connections on localhost:9876 but never sends a response. Every tool call then hangs until the MCP client gives up (~4 minutes). This is distinct from the "addon not started" case, which fails fast and clearly.
Restarting the addon changes which failure mode appears, but no state has produced a single successful tool call.
Environment
|
|
| OS |
Windows |
| Blender |
4.4+ (inferred — see note below) |
| blender-mcp |
(please fill in — uv pip show blender-mcp) |
| Python |
(please fill in — uv run python --version) |
| Client |
Claude Desktop, server managed as an extension |
| Client launch cmd |
uv run blender-mcp |
Blender version is inferred from an unrelated observation in the same session: action.fcurves raised AttributeError: 'Action' object has no attribute 'fcurves', which indicates the 4.4+ slotted-actions API.
Observed failure modes, in order
All calls below were made from the MCP client against a running Blender instance.
1. Before starting the server in Blender's sidebar
The MCP addon was enabled in Preferences, but the server had not been started from the BlenderMCP panel (viewport → N → BlenderMCP).
get_objects_summary
-> Error: Cannot connect to Blender at localhost:9876.
Ensure Blender is running with the MCP addon enabled and the server started.
This message is correct and actionable. No complaint here — including it only to establish the baseline.
2. Intermittent connection reset
get_screenshot_of_area_as_image(area_ui_type="VIEW_3D")
-> Socket error communicating with Blender at localhost:9876:
[WinError 10054] An existing connection was forcibly closed by the remote host
WinError 10054 means the peer closed an already-established connection, i.e. the listener was up and the socket was accepted, then dropped mid-exchange.
3. After starting the server — indefinite hang (the main problem)
Once the server is started from the sidebar panel, calls stop failing fast and instead hang forever:
get_objects_summary -> Tool execution failed
get_screenshot_of_window_as_json -> No result received after waiting 4 minutes
get_objects_summary -> No result received after waiting 4 minutes
The last call was made while actively moving the mouse inside the Blender 3D viewport, with the Blender window focused and in the foreground, specifically to keep the event loop busy. It still timed out.
The same hang occurred with get_blendfile_summary_path_info and execute_blender_code at the start of the session.
Suspected cause
The handler appears to be scheduled with bpy.app.timers.register(), which only fires when Blender's main event loop is processing. When it is not, the request is accepted, queued, and never serviced — which matches the symptom exactly: connection succeeds, response never arrives.
What makes this worth investigating rather than dismissing as "just focus the window": keeping the window focused and the mouse moving in the viewport did not help. So either the timer is not being registered at all in this state, or something else blocks before the timer would run.
Expected behaviour
- A request that cannot be serviced should fail fast with a diagnostic, not hang for minutes.
- A server-side timeout, so a stuck handler surfaces as an error rather than a silent hang.
- If the event loop genuinely must be active, the panel should say so and ideally warn when it detects the condition.
Suggested diagnostics to add
These would make this class of problem self-diagnosing for users:
- Log every accepted connection and every dispatched command in Blender's system console, including the timer registration result.
- Send an immediate acknowledgement on accept, before the handler runs, so the client can distinguish "not listening" / "listening but stuck" / "handler failed".
- Expose a trivial
ping command that does not touch bpy data, to isolate transport problems from data-access problems.
Additional note: Python version
Separately, we found that Python 3.14 is incompatible with blender-mcp; pinning to 3.11 (uv python pin 3.11) is required. This is not documented in the README as far as I can tell, and it causes a confusing failure for new users. Worth adding an explicit supported-versions line, and ideally a startup check that refuses to run with a clear message instead of failing obscurely.
Reproduction
Unfortunately not reliably reproducible on demand — the transition between failure modes 1 → 2 → 3 followed addon restarts, but the final hung state has been stable across multiple sessions on this machine. Happy to run any instrumented build or provide console logs.
Requests hang indefinitely on Windows: server accepts the connection on :9876 but never returns a response
Summary
On Windows,
blender-mcpreaches a state where the TCP server inside Blender accepts connections onlocalhost:9876but never sends a response. Every tool call then hangs until the MCP client gives up (~4 minutes). This is distinct from the "addon not started" case, which fails fast and clearly.Restarting the addon changes which failure mode appears, but no state has produced a single successful tool call.
Environment
uv pip show blender-mcp)uv run python --version)uv run blender-mcpObserved failure modes, in order
All calls below were made from the MCP client against a running Blender instance.
1. Before starting the server in Blender's sidebar
The MCP addon was enabled in Preferences, but the server had not been started from the
BlenderMCPpanel (viewport → N → BlenderMCP).This message is correct and actionable. No complaint here — including it only to establish the baseline.
2. Intermittent connection reset
WinError 10054means the peer closed an already-established connection, i.e. the listener was up and the socket was accepted, then dropped mid-exchange.3. After starting the server — indefinite hang (the main problem)
Once the server is started from the sidebar panel, calls stop failing fast and instead hang forever:
The last call was made while actively moving the mouse inside the Blender 3D viewport, with the Blender window focused and in the foreground, specifically to keep the event loop busy. It still timed out.
The same hang occurred with
get_blendfile_summary_path_infoandexecute_blender_codeat the start of the session.Suspected cause
The handler appears to be scheduled with
bpy.app.timers.register(), which only fires when Blender's main event loop is processing. When it is not, the request is accepted, queued, and never serviced — which matches the symptom exactly: connection succeeds, response never arrives.What makes this worth investigating rather than dismissing as "just focus the window": keeping the window focused and the mouse moving in the viewport did not help. So either the timer is not being registered at all in this state, or something else blocks before the timer would run.
Expected behaviour
Suggested diagnostics to add
These would make this class of problem self-diagnosing for users:
pingcommand that does not touchbpydata, to isolate transport problems from data-access problems.Additional note: Python version
Separately, we found that Python 3.14 is incompatible with blender-mcp; pinning to 3.11 (
uv python pin 3.11) is required. This is not documented in the README as far as I can tell, and it causes a confusing failure for new users. Worth adding an explicit supported-versions line, and ideally a startup check that refuses to run with a clear message instead of failing obscurely.Reproduction
Unfortunately not reliably reproducible on demand — the transition between failure modes 1 → 2 → 3 followed addon restarts, but the final hung state has been stable across multiple sessions on this machine. Happy to run any instrumented build or provide console logs.