You added an MCP server to claude_desktop_config.json, restarted Claude, and... nothing. No hammer icon, or the server shows red in MCP Logs. Nine issues cause ~95% of these, ranked by how often we see them.
0. Open the logs first
Before guessing, open Claude Desktop → Settings → Developer → Open MCP Logs. Each server has a mcp-server-name.log. Scan the last few lines — the error usually names itself.
1. Invalid JSON
Symptom: No hammer icon at all, even after restart.
Cause: trailing comma, missing quote, unescaped backslash.
Fix: paste config into jsonlint.com. Almost always it’s a comma after the last item.
2. Not fully quit
Closing the window keeps Claude in background. Use Cmd+Q (macOS) or Tray → Quit (Windows). Reopen. Otherwise config changes are not picked up.
3. Node / npx not in PATH
Symptom: Logs say spawn npx ENOENT.
Cause: Claude launches from Dock / Start menu, which does not inherit your shell’s PATH. npx lives in .nvm or similar.
Fix (macOS):
sudo ln -s "$(which npx)" /usr/local/bin/npx
sudo ln -s "$(which node)" /usr/local/bin/nodeOr pass absolute path in the config: "command": "/Users/you/.nvm/versions/node/v22.0.0/bin/npx".
4. Relative path in args
Filesystem MCP with "args": ["-y", "...", "./docs"] will fail. Claude resolves ./ from its launch directory, not your terminal. Always absolute paths.
5. Secret in wrong place
Env vars go in the env object, not inline in args. Common mistake:
// WRONG
"args": ["-y", "server-x", "--token=ghp_xxx"]
// RIGHT
"env": { "TOKEN": "ghp_xxx" }6. Docker MCP server: daemon not running
GitHub and a few others ship as Docker images. If Docker Desktop is closed, docker run hangs. Logs will say Cannot connect to the Docker daemon. Start Docker Desktop, relaunch Claude.
7. Server needs a specific Node version
Some MCP servers require Node 20+; you have 18. Run node --version, upgrade via nvm install 22, then either set Claude to use the upgraded binary or nvm alias default 22.
8. Windows path escaping
On Windows, paths need double backslashes in JSON:
// WRONG
"args": ["C:\Users\you\docs"]
// RIGHT
"args": ["C:\\Users\\you\\docs"]Or use forward slashes — Node accepts C:/Users/you/docs just fine.
9. Server is actually broken
Sometimes it’s not you. Test the server standalone:
npx @modelcontextprotocol/inspector npx -y <package-name> [args]If the inspector shows the error too, it’s the server, not Claude. Check the server’s GitHub issues — likely a recent breakage.
After trying all nine
If none works, share your log snippet on the r/ClaudeAI subreddit — the community is quick, but make sure you post the relevant lines, not the whole file.
Prevention
- Version-control your
claude_desktop_config.json— you’ll thank yourself after OS reinstalls. - Use one server at a time when adding new ones. Add, verify, commit, move on.
- Keep a directory bookmarks page open — install commands for every major MCP server are one click away.