Reset Claude Code configuration while preserving MCP servers
Resets Claude Code configuration while preserving MCP servers through backup and restore workflow.
/plugin marketplace add melodic-software/claude-code-plugins/plugin install claude-code-observability@melodic-software[--backup | --restore | --list-backups]Reset Claude Code configuration with MCP server preservation. This command helps you perform a clean reinstall while keeping your MCP server configurations intact.
| Argument | Description |
|---|---|
--backup | Create backup of MCP servers and settings (Step 1) |
--restore | Restore MCP servers from backup (Step 3, after relaunch) |
--list-backups | List available backups |
| (no args) | Interactive wizard guiding through full reset workflow |
┌─────────────────────────────────────────────────────────────┐
│ Reset Workflow │
├─────────────────────────────────────────────────────────────┤
│ Step 1: /user-config:reset --backup │
│ → Extracts MCP servers from ~/.claude.json │
│ → Saves to ~/.claude-backups/ │
│ │
│ Step 2: User Action (Manual) │
│ → Delete ~/.claude/ directory │
│ → Delete ~/.claude.json │
│ → Relaunch Claude Code (creates fresh config) │
│ │
│ Step 3: /user-config:reset --restore │
│ → Injects MCP servers into fresh ~/.claude.json │
│ → Optionally restores settings.json │
└─────────────────────────────────────────────────────────────┘
--backupCreate a backup before reset:
import json
import shutil
from datetime import datetime, timezone
from pathlib import Path
# Setup paths
home = Path.home()
claude_dir = home / ".claude"
claude_json = home / ".claude.json"
backup_root = home / ".claude-backups"
# Create timestamped backup directory
timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d-%H%M%S")
backup_dir = backup_root / f"backup-{timestamp}"
backup_dir.mkdir(parents=True, exist_ok=True)
backed_up = []
# 1. Extract and save MCP servers from ~/.claude.json
if claude_json.exists():
with open(claude_json) as f:
config = json.load(f)
mcp_servers = config.get("mcpServers", {})
if mcp_servers:
mcp_backup = backup_dir / "mcp-servers.json"
with open(mcp_backup, "w") as f:
json.dump(mcp_servers, f, indent=2)
backed_up.append(f"MCP servers ({len(mcp_servers)} servers) → {mcp_backup}")
# 2. Copy settings.json if exists
settings_path = claude_dir / "settings.json"
if settings_path.exists():
settings_backup = backup_dir / "settings.json"
shutil.copy2(settings_path, settings_backup)
backed_up.append(f"settings.json → {settings_backup}")
# 3. Optionally copy history.jsonl (user choice)
# history_path = claude_dir / "history.jsonl"
# if history_path.exists():
# shutil.copy2(history_path, backup_dir / "history.jsonl")
print(f"\n✅ Backup created: {backup_dir}")
for item in backed_up:
print(f" • {item}")
Output:
✅ Backup created: ~/.claude-backups/backup-2025-12-30-165217/
• MCP servers (5 servers) → mcp-servers.json
• settings.json → settings.json
Next steps:
1. Delete ~/.claude/ directory
2. Delete ~/.claude.json
3. Relaunch Claude Code
4. Run: /user-config:reset --restore
--restoreRestore MCP servers after fresh install:
import json
from pathlib import Path
home = Path.home()
claude_json = home / ".claude.json"
backup_root = home / ".claude-backups"
# Find most recent backup
backups = sorted(backup_root.glob("backup-*"), reverse=True)
if not backups:
print("❌ No backups found in ~/.claude-backups/")
exit(1)
latest_backup = backups[0]
mcp_backup = latest_backup / "mcp-servers.json"
if not mcp_backup.exists():
print(f"❌ No MCP servers backup found in {latest_backup}")
exit(1)
# Load backed-up MCP servers
with open(mcp_backup) as f:
mcp_servers = json.load(f)
# Load or create current config
if claude_json.exists():
with open(claude_json) as f:
config = json.load(f)
else:
config = {}
# Merge MCP servers (backup takes precedence)
existing_mcp = config.get("mcpServers", {})
config["mcpServers"] = {**existing_mcp, **mcp_servers}
# Save updated config
with open(claude_json, "w") as f:
json.dump(config, f, indent=2)
print(f"\n✅ Restored {len(mcp_servers)} MCP servers from {latest_backup.name}")
for name in mcp_servers.keys():
print(f" • {name}")
print("\n⚠️ Restart Claude Code to activate MCP servers")
--list-backupsList available backups:
from pathlib import Path
import json
backup_root = Path.home() / ".claude-backups"
backups = sorted(backup_root.glob("backup-*"), reverse=True)
if not backups:
print("No backups found in ~/.claude-backups/")
else:
print(f"Found {len(backups)} backup(s):\n")
for backup in backups:
mcp_file = backup / "mcp-servers.json"
settings_file = backup / "settings.json"
contents = []
if mcp_file.exists():
with open(mcp_file) as f:
mcp = json.load(f)
contents.append(f"{len(mcp)} MCP servers")
if settings_file.exists():
contents.append("settings.json")
print(f" {backup.name}")
print(f" Contents: {', '.join(contents) if contents else 'empty'}")
Guide user through the full reset workflow:
--backup logicIMPORTANT: This command does NOT perform the actual deletion. It prepares the backup and provides instructions. The user must manually delete files to prevent accidental data loss.
All backups stored in ~/.claude-backups/:
.claude/ - not affected by cleanup operationsbackup-YYYY-MM-DD-HHmmss/| Item | Backed Up | Rationale |
|---|---|---|
| MCP servers | ✅ Always | Critical - hard to recreate |
| settings.json | ✅ Always | User preferences |
| history.jsonl | ❓ Optional | Large, less critical |
| credentials | ❌ Never | Security - will re-auth |
| sessions | ❌ Never | Ephemeral, large |
| debug logs | ❌ Never | Ephemeral |
/user-config:backup - Full backup (coming soon)/user-config:restore - Full restore (coming soon)/user-config:status - Check current configuration state/user-config:audit - Validate configuration health