Claude Desktop MCP server not working? Fixes that actually work

Claude Desktop only reads its MCP config at start-up, and says little when a server fails. The log files are where the answer usually is.

Last checked 2026-10-14 against the official docs and our own test runs. See which MCP servers passed in Claude Desktop.

1. Edit the right config file

Open Settings → Developer → Edit Config. That opens (and creates if needed) claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux (beta, as on our test machine): ~/.config/Claude/claude_desktop_config.json

Servers go under the top-level "mcpServers" key. Developer settings are separate from your Claude account settings.

2. Check the JSON

One stray comma breaks the whole file, and then no server loads. JSON doesn't allow trailing commas or comments, and every key and string needs double quotes. Check the file with:

python3 -m json.tool claude_desktop_config.json

It prints the file back if it's valid, or the line and column of the first error.

3. Quit completely, then restart

Closing the window isn't enough: fully quit Claude Desktop and start it again so it reloads the config. Our test harness only counts a server as connected after this restart, when the server's start-up handshake appears in its log.

4. Check the server is listed

In a chat, click the + (“Add files, connectors, and more”) button at the bottom-left of the message box and look for your server and its tools.

5. Read the logs

Each server gets its own log, mcp-server-NAME.log, next to a general mcp.log:

macOS: ~/Library/Logs/Claude. Follow it live with tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
Windows: %APPDATA%\Claude\logs. View with type "%APPDATA%\Claude\logs\mcp*.log"
Linux beta (our tests): ~/.config/Claude/logs/mcp-server-NAME.log

These logs show connections and errors. On our machine they did not include full tool results.

6. Use absolute paths

Claude Desktop starts servers from an undefined working folder (it can be / on macOS), so ./data or a bare script name may not resolve. Use absolute paths in command, args and any .env files.

Copy the exact command and args into a terminal and run them. A stdio server that starts correctly just waits silently for input (press Ctrl+C to stop). An error, a “command not found” or a crash here is the real problem, and the app's log will show the same thing.

7. Environment variables and tokens

Servers inherit only a small set of environment variables, so your shell's PATH, API keys and tokens may be missing. Put them in the server's "env" object in the config.

On Windows, if the log shows an ENOENT error with ${APPDATA} in a path, add the expanded value of %APPDATA% to "env" as APPDATA.

Problems we actually hit in testing

From our test runs on 2026-10-13 and 2026-10-14. These apply to every client, because the cause is in the server or the machine, not the app.

Wrong Node version. context-mode needs Node 22.5 or newer and failed to start under Node 20.19 in our protocol check. Draw.io MCP also needs Node 22+. Check with node --version. If your default Node is older, install Node 22 and point command at its absolute path (for example /path/to/node22/bin/npx). That is how we made both pass.
npx / uvx not found. Most servers we test start with npx -y … (needs Node.js) or uvx … (needs uv). Apps started from a dock or menu may not see the PATH your terminal uses. Run which npx / which uvx in a terminal and use that absolute path as command.
The server needs something else running. Jupyter MCP only works with a running Jupyter server. Draw.io MCP acts on a live draw.io editor that has to be open. We failed Jupyter until a local JupyterLab was started.
No Docker. Terraform MCP's documented quick start runs it in Docker. Where Docker isn't available we used HashiCorp's official release binary as the command instead.
“Private IP” or SSRF refusals behind a proxy or VPN. On our test machine, DNS resolved public sites to 198.18.x addresses (a proxy's fake-IP range). Fetch (reference), DuckDuckGo search and Open-WebSearch have private-address guards that then refused every URL. If fetch tools fail only on one network, this is a likely cause. Each server documents its own override flag; only relax it on a network you trust.
It's the website, not your setup. DuckDuckGo search sometimes got “No results” from DuckDuckGo's bot detection. That failed a search task in one of our Cursor runs (2026-10-13) even though the server was connected and working.
One mode of a server fails while another works. Fetch (reference)'s default (readability) mode exited with an error on our machine; its raw=true option worked.

Sources

Links checked 2026-10-14. Items marked “Our tests” come from our own harness runs, shown on each server page with the date.

Other guides: Claude Code · Cursor · ChatGPT (Codex) · All help