CommunityCAD MCP
Troubleshooting
Common problems and how to fix them.
Common problems#
Start with the built-in check. In a terminal, run uvx communitycad-mcp doctor. It checks uv, the connection to CommunityCAD, your sign-in, and which AI apps have CommunityCAD set up, and tells you what to fix.
My AI app doesn't show the CommunityCAD tools#
- Run the install again. The one command is safe to run more than once; it fixes a missing or broken setup.
- Start a new session, or quit and restart the app. Most apps only load MCP servers when a session starts.
- Check the config. In Claude Code, run
claude mcp list:communitycadshould be listed as connected. In Claude Desktop, check the JSON under Settings → Developer → Edit Config: a missing comma or bracket stops every server loading. - Check uv is installed. In a terminal,
uvx --versionshould print a version. If it says the command isn't found, run the one command, which installs it, then restart your AI app so it sees it. - The app can't find
uvx(an error like "spawn uvx ENOENT"). Apps started from the dock or Start menu don't always see the same folders as your terminal. Put the full path touvxin the app's config instead of justuvx:which uvxon macOS and Linux, orwhere.exe uvxon Windows, prints it.
"Still waiting for approval"#
Your AI app has a code that hasn't been approved yet. That's normal, not a connection problem. Open the link it gave you (or go to communitycad.dev/link and type the code), sign in, and choose Approve. Then ask your AI app to finish linking.
If the code expired (after 10 minutes), ask your AI app to link again for a new one.
"Your sign-in was revoked or expired"#
The connection was unlinked on the website, or its sign-in stopped working. Your AI app has signed out and carries on with the signed-out limit. To use your account again, link it again.
"Download limit reached"#
You've used today's or this week's downloads. Your AI app tells you when they reset; it won't retry. See Downloads and limits. A model you've already downloaded today is still free to download again.
"Uploading isn't allowed"#
Your connection doesn't have the upload permission. Ask your AI app to upload again: it gives you a new code to approve the permission. See Adding the upload permission later.
"Documentation missing"#
Every upload from an AI app needs a description of at least 80 characters, a README with the required sections, and at least one picture. Nothing was uploaded, and your AI app was told exactly what's missing: let it add those and try again. See Documentation it must include.
"License required"#
A public model needs a license. Tell your AI app which one you want (see Choosing a license), or upload it as private for now.
"Too many requests"#
CommunityCAD limits how fast any app can make requests. Wait a minute, then ask again.
Pictures don't show#
Some apps' chats can't display images. Your AI app gives you the picture links instead: open them in your browser, or open the model page.
The install command fails#
It prints what went wrong and a link back here. Common causes:
- No internet connection, or a company network that blocks downloads from
astral.sh(where uv comes from). Try another network, or install uv another way, then runuvx communitycad-mcp install. - macOS or Linux without
curl: installcurl, or usewget -qO- https://communitycad.dev/mcp/install.sh | sh. - Windows says running scripts is disabled: the one command doesn't need script permission, but a saved
install.ps1does. Run the one command as shown, in PowerShell (not Command Prompt). - uv installed but "uvx isn't on PATH": open a new terminal and run
uvx communitycad-mcp install.
An update fails on Windows#
While the server is running, Windows keeps its program file locked. Quit your AI app (or end every session that uses CommunityCAD), then update again.
"File too large"#
The file is bigger than the server's limit (500 MB by default). Nothing was downloaded or counted. Download it from the model page, or raise COMMUNITYCAD_MAX_DOWNLOAD_MB (see Settings).
"Couldn't reach CommunityCAD"#
Your computer has no internet connection, or CommunityCAD is down. Try again later.
Reporting a problem#
Email [email protected], or use the contact form when signed in, with:
- what you asked, what you expected, and what happened;
- which AI app you use, and on which system (Windows, macOS or Linux);
- the exact error message, if there was one.
Please don't send the contents of your CommunityCAD config folder: it holds your sign-in.