Almost every SketchUp MCP failure is one of three things: the Ruby extension is not loaded, the MCP server is not running, or your AI client cannot start the server. Find your error string below — the fix follows it.
Two checks take a minute and will save you an hour.
In SketchUp, open Window → Ruby Console. If the extension loaded, its startup message is there; if it failed, the exception is there too, and it names the file and line. This is the single most useful place to look and most people never open it.
Then look at your AI client's tool list. If the SketchUp tools are not listed at all, the problem is between the client and the server, not inside SketchUp — skip to the spawn and config sections.
Error: spawn uvx ENOENT
What it means. Your AI client tried to launch the server and could not find the uvx command. It is not a SketchUp problem at all.
Why it happens. A GUI application does not inherit the PATH from your shell. uvx works in your terminal, so the command clearly exists — but the desktop app is looking at a different PATH and does not see it. This catches nearly everyone once.
The fix. Use the absolute path in your config instead of the bare command. Run which uvx (macOS/Linux) or where uvx (Windows) and paste the full path:
{
"mcpServers": {
"sketchup": {
"command": "/Users/you/.local/bin/uvx",
"args": ["sketchup-mcp"]
}
}
}
Restart the client fully afterwards.
Error executing MCP tool: Not connected
What it means. The client registered the server, but the connection is not live at the moment the tool was called. The server either never started, or started and exited.
The fix. Both halves have to be running: SketchUp open with the extension loaded, and the MCP server process alive. Start the server first, then SketchUp, then the client. If the server exits immediately, run its command by hand in a terminal — the error it prints on startup is usually clear and is hidden entirely when the client launches it.
Connection refused. Is the MCP server running?
What it means. Something tried to reach the server at a specific address and nothing answered there.
The fix. Check the URL or port in your config against what the server actually binds to. A missing path segment or a typo in the port is the usual cause. If you are on the open-source route, confirm which port the project uses — implementations differ, and 9876 and 8080 are both in use.
What it means. The client cannot establish the connection and is waiting. You would see exactly the same thing if you had never started the server, which is why this one is so unhelpful.
The fix. Treat it as “not connected” rather than “slow”. Work through the spawn check and the config-syntax check below; it is almost always one of those two.
What it means. Your client did not read the configuration — usually because the JSON is invalid, and many clients fail silently rather than reporting it.
The fix. Paste the file into any JSON validator. The three things that break it: a trailing comma after the last entry, curly “smart quotes” from copying out of a web page or a PDF, and an unescaped backslash in a Windows path. Windows paths need doubled backslashes:
"command": "C:\\Users\\you\\.local\\bin\\uvx.exe"
Then quit the client completely and reopen it. Most clients only read the config at startup.
What it means. The .rbz installed, the extension shows up in Extension Manager, and commands still do nothing.
The fix. Three things to check, in order:
What it means. SketchUp's Ruby API changes between releases, and an extension written against one version may not load in another. A major-version upgrade is the usual trigger.
The fix. Check the project's stated version support and reinstall the build that matches your SketchUp. This is a recurring cost of the open-source route rather than a one-off.
What it means. Usually a port conflict. The extension loads, the server starts, neither reports an error, and they are not talking to each other because something else already holds the port.
The fix. Check what is on the port before assuming it is free:
lsof -nP -iTCP:9876 -sTCP:LISTEN # macOS / Linux netstat -ano | findstr :9876 # Windows
If something is there, either stop it or change the port in both the extension's settings and the server's configuration. Changing one and not the other produces exactly the same silent failure.
What it means. The request was too large for one round trip. Long operations across many objects are the usual cause.
The fix. Break the request into smaller steps. “Array the seating, then assign materials” works where “build the whole lounge” times out. This is a real limit of the current generation of tooling, not a configuration mistake.
Every failure on this page is one ZirenAI handles for you. It installs the extension and the runtime SketchUp needs, wires them together, and re-checks the connection before every run — naming the failing part instead of leaving you to read a stack trace.
Download for Windows