MCP Servers Not Connecting in Claude: The Complete Troubleshooting Guide

🚀 Quick Diagnostic Script

#!/bin/bash
# MCP Connection Diagnostic v2.0

echo "🔍 MCP Server Diagnostic Starting..."
echo "================================="

# Check Node.js
echo "
1. Node.js Check:"
if command -v node &> /dev/null; then
    echo "✅ Node installed: $(node -v)"
    echo "📍 Path: $(which node)"
else
    echo "❌ Node.js not found!"
fi

# Check NPM
echo "
2. NPM Check:"
if command -v npm &> /dev/null; then
    echo "✅ NPM installed: $(npm -v)"
else
    echo "❌ NPM not found!"
fi

# Check Claude Desktop config
echo "
3. Config File Check:"
CONFIG_PATH="~/Library/Application Support/Claude/claude_desktop_config.json"
if [ -f "$CONFIG_PATH" ]; then
    echo "✅ Config file exists"
    echo "📝 Validating JSON..."
    if python3 -m json.tool "$CONFIG_PATH" > /dev/null 2>&1; then
        echo "✅ Valid JSON syntax"
    else
        echo "❌ Invalid JSON syntax!"
    fi
else
    echo "❌ Config file not found!"
fi

# Check NVM
echo "
4. NVM Check:"
if [ -s "$HOME/.nvm/nvm.sh" ]; then
    echo "⚠️  NVM detected - common cause of issues"
    echo "📍 NVM Node: $(nvm which current 2>/dev/null || echo 'Not set')"
else
    echo "✅ No NVM conflicts"
fi

echo "
================================="
echo "📊 Diagnostic complete!"

🔧 GUI App PATH Fix

Create a wrapper script that explicitly sets the PATH:

#!/bin/bash
# Save as: ~/mcp-launcher.sh
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
exec /opt/homebrew/bin/node "$@"

Then update your config:

"command": "/Users/yourname/mcp-launcher.sh"

🛠️ MCP Config Validator & Fixer

#!/usr/bin/env python3
# Save as: validate-mcp-config.py

import json
import os
import sys
from pathlib import Path

def validate_mcp_config(config_path):
    """Validate and fix MCP configuration"""
    
    # Read config
    try:
        with open(config_path, 'r') as f:
            config = json.load(f)
        print("✅ Valid JSON syntax")
    except json.JSONDecodeError as e:
        print(f"❌ JSON Error: {e}")
        return False
    
    # Check structure
    if 'mcpServers' not in config:
        print("❌ Missing 'mcpServers' key")
        config['mcpServers'] = {}
    
    # Validate each server
    for server_name, server_config in config['mcpServers'].items():
        print(f"
🔍 Checking {server_name}...")
        
        # Check required fields
        if 'command' not in server_config:
            print(f"  ❌ Missing 'command' field")
            continue
            
        # Verify command exists
        command = server_config['command']
        if not os.path.exists(os.path.expanduser(command)):
            print(f"  ⚠️  Command not found: {command}")
            
        print(f"  ✅ Valid configuration")
    
    # Save backup and fixed version
    backup_path = config_path + '.backup'
    with open(backup_path, 'w') as f:
        json.dump(config, f, indent=2)
    print(f"
💾 Backup saved to {backup_path}")
    
    return True

if __name__ == "__main__":
    config_path = "~/Library/Application Support/Claude/claude_desktop_config.json"
    config_path = os.path.expanduser(config_path)
    validate_mcp_config(config_path)

🔬 Enable Debug Logging

Add verbose logging to see exactly what's failing:

{
  "mcpServers": {
    "your-server": {
      "command": "node",
      "args": ["--inspect", "index.js"],
      "env": {
        "DEBUG": "*",
        "NODE_ENV": "development",
        "MCP_VERBOSE": "true"
      }
    }
  }
}

Then check logs in Console.app (Mac) or Event Viewer (Windows).