Part 9 — Troubleshooting

Even a clean setup hits friction eventually. The good news: almost every problem in this stack falls into one of two buckets — the bridge is broken (Claude Code cannot reach Blender), or the bridge works but the result Claude produced is messy. This chapter walks through five common cases. The first two are connection issues you fix once; the last three are scene-quality issues you fix with a prompt — no Python, no manual mesh surgery, just describe what you want.

Problem 1 — Claude Code says Blender MCP is not connected

This means the socket between the MCP server and the Blender add-on never came up. The add-on and the blender-mcp server talk over a socket, with defaults BLENDER_HOST=localhost and BLENDER_PORT=9876. Walk this checklist top to bottom — it follows the order the connection is built:

• Blender 5 is actually open and running.
• The Blender MCP add-on is enabled (the checkbox next to Interface: Blender MCP is ticked in Edit → Preferences → Add-ons).
• The BlenderMCP sidebar is visible — in the 3D Viewport press N to open the Sidebar, then select the BlenderMCP tab.
• You clicked Connect to Claude in that tab (this opens the socket on the Blender side).
• Claude Code sees the server — run claude mcp list in the terminal, and /mcp inside Claude Code, and confirm blender appears.
• Only one Blender instance with the add-on is connected. The add-on is what binds port 9876 (the blender-mcp server connects to it as a client), so a second Blender add-on trying to bind the same port — or several Claude/MCP clients pointed at one Blender — will confuse or block the connection.

Problem 2 — uvx works in the terminal but not in Claude Code

You run uvx --version in your terminal and it answers fine, yet Claude Code reports something like spawn uvx ENOENT. The cause is the environment, not a broken install: GUI-launched apps may not inherit the same PATH your interactive shell has, so the launched process literally cannot find the uvx executable.

Two fixes. Either point the config at the full absolute path to uvx, or on Windows wrap the command with cmd /c so the system resolver finds it for you:

{"mcpServers":{"blender":{"command":"cmd","args":["/c","uvx","blender-mcp"]}}}

Problem 3 — Claude creates messy objects

After a few rounds of edits, the Outliner fills up with stray cubes, generic names like Cube.001, and accidental duplicates. You do not clean this by hand. You ask Claude to inspect the scene and reorganize it — it can read the hierarchy, move objects into collections, rename, and delete on your behalf. Copy this prompt verbatim:

Inspect the scene and clean the hierarchy.
Rules:
- Move every object into the correct collection
- Rename generic objects
- Delete accidental duplicates
- Merge or simplify unnecessary repeated objects
- Report the final object count

Asking for the final object count at the end gives you a quick way to confirm the cleanup actually happened rather than trusting the Outliner alone.

Problem 4 — Model is too complex

The scene looks right but it is too heavy — too many objects, fussy materials, tiny details no one will ever see. For game use or a lighter export, ask Claude to simplify while preserving the visual idea. Copy this prompt verbatim:

Simplify this scene for game use.
Requirements:
- Keep the same visual idea
- Reduce object count where possible
- Use simple materials
- Keep low-poly style
- Remove tiny unnecessary details
- Report what was simplified

The “Report what was simplified” line matters: it turns a vague request into an auditable change list, so you can spot if anything important was stripped out.

Problem 5 — The output looks bad

Sometimes the geometry is fine but the presentation is weak — a flat camera angle, muddy lighting, shapes that read as a blob. This is a composition problem, and Claude can fix it without adding new complexity. Copy this prompt verbatim:

Improve the scene composition.
Focus on:
- better camera angle
- clearer silhouette
- more readable shapes
- better lighting
- cleaner spacing between objects.
Do not add unnecessary complexity.