Claude Desktop MCP Not Working

Overview: Why Claude Desktop MCP Stops Working

Claude Desktop is the most popular MCP client, and it has specific configuration requirements that differ from other clients. When MCP stops working, the cause is almost always in the config file, server process, or permissions. This guide covers every known issue and fix.

Before diving in, check the basics: make sure you have the latest version of Claude Desktop installed, and that you're signed in. MCP support requires Claude Desktop 1.x or later.

Step 1: Find Your Config File

Claude Desktop reads MCP server configuration from a JSON file. The location depends on your operating system:

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Open it with:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

In Explorer, paste this into the address bar:

C:\Users\YOUR_USERNAME\AppData\Roaming\Claude\claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

If the file doesn't exist, create it with this minimal valid content:

{
  "mcpServers": {}
}

Step 2: Validate Your JSON

The most common cause of MCP not working is invalid JSON in the config file. Claude Desktop silently fails if the JSON is malformed - no error dialog, just no MCP servers loading.

Common JSON Mistakes

// WRONG - trailing comma (most common mistake)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],  // <- trailing comma!
    }
  }
}

// WRONG - unescaped backslashes in Windows paths
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\Users\me\Docs"]
    }
  }
}
// Must use \\ for each backslash: "C:\\Users\\me\\Docs"

// WRONG - comments in JSON (JSON doesn't support comments)
{
  // This breaks everything
  "mcpServers": {}
}

// CORRECT - minimal working config
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

Validate your JSON at jsonlint.com or with this command:

python3 -c "import json; json.load(open('claude_desktop_config.json'))"

Step 3: Check Server Startup

Even with valid JSON, the server process might fail to start. Test the server manually in your terminal:

# Copy the exact command from your config and run it
npx -y @modelcontextprotocol/server-filesystem /tmp

# You should see the server start without errors
# Press Ctrl+C to stop

If this fails, see our spawn ENOENT guide for executable path fixes.

Step 4: Check Claude Desktop Logs

Claude Desktop writes detailed MCP logs that show exactly what went wrong:

macOS Log Location

~/Library/Logs/Claude/mcp.log
~/Library/Logs/Claude/mcp-server-*.log

View them with:

tail -f ~/Library/Logs/Claude/mcp*.log

Windows Log Location

%APPDATA%\Claude\logs\mcp.log

What to Look For

Common log entries and their meanings:

# Server crashed immediately
[ERROR] Server "filesystem" exited with code 1
[ERROR] stderr: Error: Cannot find module '@modelcontextprotocol/server-filesystem'

# Server started but returned invalid response
[ERROR] Server "filesystem" sent invalid JSON on stdout
[WARN] Unexpected data on stderr: "Warning: some deprecation notice"

# Permission denied
[ERROR] spawn EACCES: permission denied '/usr/local/bin/npx'

# Config parsing failed
[ERROR] Failed to parse claude_desktop_config.json

Step 5: Restart Claude Desktop Properly

Closing the Claude Desktop window does NOT stop the application. You must fully quit it:

macOS

• Click Claude in the menu bar > Quit Claude
• Or use Cmd+Q
• Or: killall Claude in terminal

Windows

• Right-click the Claude icon in the system tray > Exit
• Or: taskkill /IM Claude.exe /F in Command Prompt

Then relaunch the app. MCP servers are initialized only at app startup.

Step 6: Permission Issues

macOS Permissions

Claude Desktop needs file access permission for MCP servers that read/write files. If you see permission errors:

1. Open System Settings > Privacy & Security > Files and Folders
2. Find Claude and enable access to the directories your MCP servers need
3. For Full Disk Access, go to Privacy & Security > Full Disk Access and add Claude

File Path Permissions

The filesystem MCP server only allows access to directories you explicitly list in the args. Make sure the paths exist and are readable:

# Check that the path exists and is readable
ls -la /path/you/specified/in/config

Step 7: Multiple Server Configuration

When running multiple MCP servers, one broken server can sometimes affect others. Isolate the issue by testing one server at a time:

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

If this works, add servers back one at a time to find the problematic one.

Step 8: Environment Variables

Some MCP servers require API keys or other environment variables. Claude Desktop supports the "env" field in server config:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

See our full environment variables guide for details on secrets management.

Common Pitfalls

• Editing config while Claude is running - Changes only take effect after a full restart.
• Using relative paths - Always use absolute paths in the config. ~ and ./ are not expanded.
• Windows path separators - Use double backslashes \\ or forward slashes / in JSON.
• Wrong npx version - If you have multiple Node.js installations, Claude Desktop might use a different npx than your terminal.
• Corporate proxy - Corporate proxies can prevent npx from downloading packages. Pre-install with npm install -g instead.

For Cursor-specific MCP issues, see our Cursor MCP troubleshooting guide. For integration tutorials, check the Claude integration tutorial.