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 like Cursor or VS Code. When MCP stops working, the cause is almost always in the config file, server process, or permissions. This guide walks through every known issue systematically so you can diagnose and fix the problem quickly.

Before diving in, check the basics: make sure you have the latest version of Claude Desktop installed (check Help, About or download from the official site), make sure you are signed in, and confirm that your subscription plan supports MCP. MCP support requires Claude Desktop 1.x or later and is available on all paid plans.

Step 1: Find Your Config File

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

Operating System	Config File Path	Quick Open Command
macOS	~/Library/Application Support/Claude/claude_desktop_config.json	open ~/Library/Application\ Support/Claude/
Windows	%APPDATA%\Claude\claude_desktop_config.json	Paste %APPDATA%\Claude in Explorer
Linux	~/.config/Claude/claude_desktop_config.json	xdg-open ~/.config/Claude/

If the file does not exist, create it with this minimal valid content:

{
  "mcpServers": {}
}

Make sure the directory also exists. On macOS, the ~/Library/Application Support/Claude/ directory is created automatically when Claude Desktop runs for the first time. If it does not exist, launch Claude Desktop once before creating the config file.

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 appears, no warning notification, just no MCP servers loading. This silent failure is the source of enormous frustration because everything looks normal.

Common JSON Mistakes

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

// 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"
// Or use forward slashes: "C:/Users/me/Docs"

// WRONG - comments in JSON (JSON does not support comments)
{
  // This breaks everything
  "mcpServers": {}
}

// WRONG - single quotes instead of double quotes
{
  'mcpServers': {}
}

// WRONG - unquoted keys
{
  mcpServers: {}
}

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

Validating JSON Programmatically

Use one of these methods to validate your JSON before restarting Claude Desktop:

# Python (works on all platforms)
python3 -c "import json; json.load(open('claude_desktop_config.json')); print('Valid JSON')"

# Node.js
node -e "require('./claude_desktop_config.json'); console.log('Valid JSON')"

# jq (macOS/Linux)
jq . claude_desktop_config.json

# PowerShell (Windows)
Get-Content claude_desktop_config.json | ConvertFrom-Json

You can also use online validators like jsonlint.com, but be cautious about pasting config files that contain API keys or tokens into online tools. For configs with secrets, use the local command-line validators above.

Step 3: Check Server Startup

Even with valid JSON, the server process might fail to start. Test the server manually in your terminal by copying the exact command and arguments from your config:

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

# You should see the server start without errors
# It will wait for input on stdin (this is normal for stdio servers)
# Press Ctrl+C to stop

If this fails with an error, address that error first. Common issues:

• ENOENT - The command is not found. See our spawn ENOENT guide.
• MODULE_NOT_FOUND - The npm package failed to download. Check your internet connection and npm registry access.
• EACCES - Permission denied. The executable needs execute permissions. Run chmod +x on the binary.
• SyntaxError - Your Node.js version is too old for the server. Upgrade to Node.js 18+.

Step 4: Check Claude Desktop Logs

Claude Desktop writes detailed MCP logs that show exactly what went wrong during server initialization. These logs are your best diagnostic tool.

Log File Locations

OS	Log Directory	View Command
macOS	~/Library/Logs/Claude/	tail -f ~/Library/Logs/Claude/mcp*.log
Windows	%APPDATA%\Claude\logs\	Open folder in Explorer, open mcp.log
Linux	~/.config/Claude/logs/	tail -f ~/.config/Claude/logs/mcp*.log

Log files include mcp.log (general MCP events) and mcp-server-SERVERNAME.log (per-server output including stderr from the server process).

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 sent invalid output
[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 (JSON syntax error)
[ERROR] Failed to parse claude_desktop_config.json
[ERROR] Unexpected token } in JSON at position 234

# Server timed out during initialization
[ERROR] Server "my-server" failed to initialize within 30000ms
[ERROR] Timeout waiting for server ready signal

Step 5: Restart Claude Desktop Properly

Closing the Claude Desktop window does NOT stop the application or reinitialize MCP servers. You must fully quit and relaunch it. MCP servers are only initialized during application startup.

Proper Restart Procedures

OS	Quit Method	Terminal Force Quit
macOS	Menu bar: Claude, Quit (or Cmd+Q)	killall Claude
Windows	System tray: right-click, Exit	taskkill /IM Claude.exe /F
Linux	Close from application menu or taskbar	killall claude-desktop

After quitting, wait a few seconds for all MCP server processes to terminate, then relaunch the app. You can verify all processes are stopped by checking: ps aux | grep -i claude (macOS/Linux) or tasklist | findstr Claude (Windows).

Step 6: Process Monitoring

Sometimes Claude Desktop starts but the MCP server processes crash silently. Monitor server processes to verify they are running:

# macOS/Linux - watch for MCP server processes
ps aux | grep -E "(mcp|npx|uvx)" | grep -v grep

# Watch processes in real-time (macOS/Linux)
watch -n 2 'ps aux | grep -E "(mcp|npx)" | grep -v grep'

# Windows - check for node processes (MCP servers run as node)
tasklist | findstr node
Get-Process | Where-Object { $_.ProcessName -match "node" }

If you see server processes starting and immediately dying, the server is crashing on startup. Check the per-server log file (mcp-server-SERVERNAME.log) for the crash error.

Step 7: Permission Issues

macOS Permissions

Claude Desktop needs file access permissions for MCP servers that read or write files. If you see permission errors in the logs:

1. Open System Settings, Privacy and Security, Files and Folders
2. Find Claude and enable access to the directories your MCP servers need
3. For broader access, go to Privacy and Security, Full Disk Access, and add Claude
4. You may also need to allow Claude through the application firewall if using HTTP-based MCP servers

Windows Permissions

On Windows, common permission issues include:

• Windows Defender blocking the npx process - add Node.js directory to exclusions
• User Account Control (UAC) preventing access to certain directories
• Antivirus quarantining downloaded npm packages

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

# Check permissions recursively
ls -laR /path/you/specified/in/config | head -20

Step 8: Multiple Server Configuration

When running multiple MCP servers, one broken server can sometimes affect the startup of others. Claude Desktop initializes servers in parallel, but a config-level JSON error prevents all servers from loading. Isolate the issue by testing one server at a time:

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

If this single server works, add servers back one at a time to find the problematic one. See our multiple server configuration guide for best practices on running many servers simultaneously.

Step 9: Environment Variables

Some MCP servers require API keys or other environment variables. Claude Desktop supports the "env" field in server config. Variables set here are passed only to the specific server process - they do not affect other servers or Claude Desktop itself.

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

Important: Claude Desktop does NOT inherit your shell's environment variables. If you set GITHUB_TOKEN in your .bashrc or .zshrc, Claude Desktop will not see it. You must explicitly set it in the "env" field. See our full environment variables guide for details on secrets management and per-client differences.

Step 10: Version and Update Issues

MCP-related issues can appear after updating Claude Desktop or the MCP server packages. Common update-related problems:

• Claude Desktop update changed config format - Check the release notes for any breaking changes to the config schema.
• Server package was updated and changed behavior - Clear the npx cache and re-download: npx clear-npx-cache, then restart.
• Node.js was updated and broke compatibility - Some servers require specific Node.js versions. Check the server's README for version requirements.
• Config file was overwritten by update - Check if your config file still contains your server definitions. Some users report config files being reset after updates.

Common Pitfalls

• Editing config while Claude is running - Changes only take effect after a full quit and relaunch. Cmd+Q on macOS, Exit from system tray on Windows.
• Using relative paths - Always use absolute paths in the config. ~, ./, and ../ are not expanded by the JSON parser.
• Windows path separators - Use double backslashes \\ or forward slashes / in JSON. Single backslashes are JSON escape characters.
• Wrong npx version - If you have multiple Node.js installations (nvm, system, Homebrew), Claude Desktop might use a different npx than your terminal. Use absolute paths to avoid ambiguity.
• Corporate proxy - Corporate proxies can prevent npx from downloading packages. Pre-install with npm install -g @modelcontextprotocol/server-filesystem instead of relying on npx -y.
• Disk space - npx downloads packages to a cache directory. If disk space is low, downloads may fail silently. Check available space on the drive containing your npm cache.
• VPN interference - Some VPNs redirect localhost traffic, which can break stdio communication between Claude Desktop and MCP servers. Try disconnecting VPN to test.

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