Troubleshooting

Server Won't Start

If clicking Start Server does nothing or immediately fails, another process is likely already bound to the configured port (7842 by default). Either close whatever's using it, or change the port in Preferences and try again — see Installation & Server Setup.

Connected Client Isn't Working

Confirm the server shows "Running" in the main panel before writing a client config — a config written while the server is stopped will point at a dead endpoint.
Fully quit and reopen the client application after writing its config; a soft reload usually isn't enough for Claude Desktop, Cursor, or Windsurf to pick up a new MCP server.
If you changed the port after already connecting a client, reconnect it — old configs keep pointing at the previous port.
For Claude.ai (web), confirm cloudflared or ngrok is actually installed and on your system PATH; the panel reports this explicitly if it can't find either.

Tool Calls Timing Out

Most tools dispatch to Blender's main thread and wait up to 30 seconds for a result; viewport screenshots wait up to 15 seconds. If a call times out:

Check whether Blender itself is blocked on something else (a modal operator, a long-running render) — tool calls can't run while the main thread is busy elsewhere.
For very heavy operations (huge decimation targets, large batch exports), break the request into smaller steps rather than one call covering the whole scene.

Only Scene Tools Are Available

This means no valid Pro license is active. Enter your Superhive license key in Preferences — see Licensing. If you've entered a key and it's still not validating, check your network connection; if the license server is unreachable, a 14-day grace period should kick in automatically and unlock full access in the meantime.

Chat Provider Errors

No response / auth error — double-check the API key for your selected provider in Preferences; keys are provider-specific and won't work if pasted into the wrong field.
Ollama times out or ignores tool calls — this is expected on very small models. Switch to at least qwen2.5:3b, or a cloud provider, for reliable tool use. The chat engine already caps Ollama at fewer tool-use loops than cloud providers to fail faster rather than hang.
Gemini errors on some requests — make sure you're on a current Gemini model (the default gemini-2.5-flash is recommended); older or mismatched model names can behave inconsistently with tool calling.

Armature Tool Errors

Armature tools need an active VIEW_3D context to run correctly. If you're seeing context-related errors from bone or rig operations, make sure a 3D Viewport is visible and not maximized-out by another editor area when the AI issues the call.

Expected Addon Tool Isn't Showing Up

The addon scanner runs once, a few seconds after Blender starts, and caps out at 50 discovered operators. If an addon you installed after that scan isn't showing up, restart Blender to trigger a fresh scan. Note also that entire categories of built-in operators (sculpt, physics, animation editors, file/window management) and a short list of destructive exact operators are always excluded from discovery — this is intentional and not adjustable.

Meshy Job Stuck In Progress

Generation happens on Meshy's servers, not locally — a job showing "in progress" for longer than expected is a Meshy-side queue or processing delay, not a BlenderMCP Pro issue. Use meshy_get_job_status to check current progress, or check your job directly on meshy.ai.

Voice Input Reports Unavailable

Install both PyAudio and Whisper (either the whisper pip package or the CLI on PATH), then restart Blender. See Voice Input for details.

Getting More Help

If none of the above resolves your issue, reach out on the Quadify Discord or email support@theanvilstore.com with your Blender version, OS, and the exact error text.