mcp-config-fix

MCP Config Fix — Claude Desktop Windows

⚠️ SECURITY NOTICE

This skill modifies your Claude Desktop configuration file.

• NEVER run commands from this skill without reading them first
• NEVER paste API keys directly — use environment variables instead
• ALWAYS back up your config before running any fix
• This skill will NEVER ask you to download or run external scripts

The Problem

On Windows, Claude Desktop silently fails to load MCP servers when the config file has a UTF-8 BOM (Byte Order Mark). PowerShell's Set-Content -Encoding UTF8 adds a 3-byte BOM (EF BB BF) to the beginning of files. Claude Desktop cannot parse JSON with BOM → ignores mcpServers → overwrites the file with only preferences.

Root Cause

❌ PowerShell Set-Content -Encoding UTF8  → adds BOM → Claude Desktop ignores mcpServers
❌ Notepad "Save as UTF-8"               → adds BOM → same problem
✅ [System.IO.File]::WriteAllText()       → no BOM  → works perfectly

The Fix — ALWAYS Use This Method

Step 1: Kill Claude Desktop FIRST

IMPORTANT: Never kill processes named "Claude" generically — this will kill Claude Code too!

# Safe way — only kills Claude Desktop, NOT Claude Code
Get-Process | Where-Object {$_.ProcessName -eq "Claude Desktop" -or ($_.MainWindowTitle -like "*Claude*" -and $_.ProcessName -ne "claude")} | Stop-Process -Force -ErrorAction SilentlyContinue

Or better: Ask the user to manually quit Claude Desktop from the system tray (right-click → Quit). This is the safest approach.

Step 2: Back Up Existing Config

ALWAYS create a backup before modifying anything:

$configPath = "$env:APPDATA\Claude\claude_desktop_config.json"
if (Test-Path $configPath) {
    $backupPath = "$env:APPDATA\Claude\claude_desktop_config.backup.$(Get-Date -Format 'yyyyMMdd-HHmmss').json"
    Copy-Item $configPath $backupPath
    "Backup saved to: $backupPath"
} else {
    "No existing config found — skipping backup"
}