MCP server not loading in Claude Desktop: 9 common fixes

You added a server to claude_desktop_config.json, restarted the app, and … nothing. No hammer icon, or tools list is empty. Here is the nine-item checklist we run through before anything else — ordered by how often each one is actually the culprit.

1. You didn't fully quit Claude Desktop

The single most common cause. Closing the window keeps the app alive in the background and the config stays cached.

macOS: Cmd+Q, or right-click in the Dock → Quit.
Windows: right-click the tray icon → Quit.

Confirm: reopen and check the hammer icon in the chat composer. Fix rate: ~40%.

2. Invalid JSON in the config

A trailing comma, a missing brace, a stray smart quote from copy-pasting out of a blog post — any of these silently break the whole config. Paste the file into jsonlint.com before saving. If JSONLint is green, move on.

3. Relative path instead of absolute

Claude Desktop resolves paths from its own working directory, not your terminal. ./Documents or ~/Documents will point somewhere unexpected.

// Wrong
"args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Documents"]

// Right
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]

Always use the absolute path. On Windows, double-escape backslashes: C:\\Users\\you\\Docs.

4. Node / npx not on Claude's PATH

Classic on macOS. When Claude Desktop launches from the Dock it does not source your .zshrc, so any Node version installed by nvm is invisible.

Quick test in Terminal: which npx. Likely output: /Users/you/.nvm/versions/node/v22.x/bin/npx. Claude needs that in PATH. Either symlink npx to /usr/local/bin/ or install Node via Homebrew so it lives on the default PATH.

5. Config file in the wrong location

The path is OS-specific:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Easiest way to get there correctly: Claude Desktop → Settings → Developer → Edit Config.

6. Server package fails to install

When Claude launches the server with npx, it may fail silently if offline, behind a proxy, or the package is deprecated. Run the exact command from your config in Terminal:

npx -y @modelcontextprotocol/server-filesystem /Users/you/Documents

If it errors there, it errors the same way in Claude. Fix the error before retrying.

7. Missing environment variables

Servers that need a token (GitHub, Postgres, Stripe) will start but return zero tools. Put secrets in the env object, not inline in args:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
               "ghcr.io/github/github-mcp-server"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
    }
  }
}

8. MCP Logs tell you exactly what's wrong

Settings → Developer → MCP Logs shows the stderr output of each server process. 90% of the remaining bugs are identified at a glance. Common log signatures:

ENOENT: no such file or directory → path issue (see #3 and #5)
Unable to validate token → env var missing or expired
Error: Cannot find module → Node/npx PATH (see #4)
Connection closed → server crashes on startup (see #6)

9. Claude Desktop version-specific bugs

Claude Desktop pushed MCP-breaking changes in early 2026. If everything looks right and nothing works, verify you're on Claude Desktop 1.2+. Older versions had a bug where stdio servers hung forever if the first message exceeded 4 KB.

Still stuck?

Post a question in our submit channel or open an issue on the server's GitHub. Include: config JSON (redact secrets), MCP Log output, Claude Desktop version.