MCP Server Not Connecting in Claude Desktop: How to Fix It (Windows, macOS, Linux)

When a local MCP server will not connect in Claude Desktop, the app either never read your config or could not start the server. The fastest fix is three steps: check that claude_desktop_config.json is valid JSON with an mcpServers key, fully quit and reopen Claude Desktop, then open mcp.log and read the line about your server. That log line nearly always names the real cause.

Checked against: the MCP guide to connecting local servers, the MCP debugging guide, the build-a-server tutorial's troubleshooting section and Claude's help article on local MCP servers on 2 November 2026. eSEOspace did not run these steps on each operating system; follow the vendor page if a menu differs.

What this error means

Claude Desktop starts each local server as a child process using the stdio transport. It runs the command from your config, passes the args, and talks to the program over standard input and output.

"Not connecting" covers several symptoms. The server may not appear under Connectors, it may show an error badge, or a pop-up may say it could not attach. The MCP debugging guide groups the causes into path issues, configuration errors and environment problems.

Remote connectors that you add by URL are a different flow. For those, see the MCP 401 guide, which also covers sign-in and redirect problems.

Quick fix

1. Open the right file. In Claude Desktop, open Settings > Developer and select Edit Config. The local server guide lists the paths: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, and ~/.config/Claude/claude_desktop_config.json on Linux.
2. Check the JSON. Every server must sit inside one mcpServers object. A trailing comma or missing brace stops the whole file from loading.
3. Use absolute paths. The debugging guide says the working directory "may be undefined (like / on macOS)," so ./data will not work.
4. Quit fully. The build tutorial says to use Cmd+Q on macOS, or right-click the tray icon and choose Quit on Windows and Linux. Closing the window is not enough.
5. Read the log. Look for your server's name in mcp.log and in mcp-server-SERVERNAME.log.
6. Run it by hand. Paste the same command into a terminal. If it fails there, fix that error first.

A minimal valid config looks like this (from the MCP local server guide):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop"
      ]
    }
  }
}

You can build and check a config with the free MCP config generator.

Fix by client / OS

Claude Desktop on macOS

If the log says the command was not found, the app cannot see the tool on your shell PATH. A GitHub thread on MCP servers and nvm shows the common workaround: point command at the full path of node and the server script instead of npx. An MCP maintainer explained in that thread that "the environment for GUI apps is completely different from what you see on the command line." Use which node in Terminal to get the full path.

Claude Desktop on Windows

Write paths with double backslashes, such as C:\\Users\\you\\Desktop, as the build tutorial notes. If the log mentions ${APPDATA} in a path, the local server guide says to add the expanded APPDATA value to the server's env block and to install npm globally. The full list of Windows causes is in MCP server failed to start on Windows.

Claude Desktop on Linux

The MCP docs list ~/.config/Claude/logs for logs. The build tutorial says you can quit with pkill -f claude-desktop if the tray icon is hidden.

Desktop extensions

If you installed the server as a desktop extension instead of editing JSON, Claude's help article says Claude Desktop "includes a built-in Node.js environment," and suggests restarting the app "to refresh the extension registry." Team and Enterprise owners can turn public extensions off, so ask your admin if the install button is missing.

Where to find the logs

The MCP debugging guide gives these log folders:

mcp.log covers connection events. mcp-server-SERVERNAME.log contains the stderr output of that server, so a stack trace from your server lands there.

For client-side errors, the same guide shows how to turn on Chrome DevTools inside Claude Desktop with a developer_settings.json file containing {"allowDevTools": true}. Then press Command-Option-I on macOS or Ctrl+Alt+I on Windows.

Paste any JSON-RPC error code you find into the MCP error code lookup.

If it still fails

• Test outside Claude. Run the server in the MCP Inspector. If it fails there too, the bug is in the server. If it works there, read works in Inspector but not in Claude.
• Look for stray output. A server that prints banners to stdout corrupts the protocol. See stdout logging breaks the server.
• Check the runtime. spawn npx ENOENT or uvx not found means a missing launcher. See spawn npx ENOENT.
• Ask for help with evidence. The debugging guide suggests sharing log excerpts, your config file, steps to reproduce and environment details. Remove API keys first.

If your team keeps hitting setup problems across many machines, an MCP readiness audit can standardize configs and approved servers.

Frequently asked questions