Obsidian × MCPVault: The Vault Health Check

The Stack

Tested Against

Prerequisites

• Claude Code, and register MCPVault: `claude mcp add obsidian --scope user npx @bitbonsai/mcpvault /Users/you/Documents/MyVault`
• Node 20+ (MCPVault runs via npx)
• cron (built into macOS/Linux)
• Back up your vault first (git ideal)

Steps

1. 1

   Validate config, write the scheduled script, check the cron

   CI validates the MCPVault config, writes the exact vault-health-check.sh from the guide (executable, carrying the claude -p call), scaffolds Maintenance/, and confirms the monthly cron line is well-formed.

   cat > claude_desktop_config.json <<'EOF'
   { "mcpServers": { "obsidian": { "command": "npx", "args": ["@bitbonsai/mcpvault@latest", "/Users/you/Documents/MyVault"] } } }
   EOF
   node -e 'const c=JSON.parse(require("fs").readFileSync("claude_desktop_config.json","utf8"));const o=c.mcpServers.obsidian;if(o.command==="npx"&&o.args.some(a=>a.indexOf("@bitbonsai/mcpvault")===0)){console.log("config OK: npx -> @bitbonsai/mcpvault")}else{console.log("BAD");process.exit(1)}'
   mkdir -p vault/Maintenance bin
   cat > bin/vault-health-check.sh <<'EOF'
   #!/usr/bin/env bash
   claude -p "Audit my Obsidian vault using the obsidian MCP tools. Find orphan notes with no incoming links, notes whose information looks outdated, projects with no update in 2 weeks, tags used inconsistently, and notes missing expected frontmatter fields. Write the findings to Maintenance/$(date +%F)-health-check.md as a fix-it checklist."
   EOF
   chmod +x bin/vault-health-check.sh
   test -x bin/vault-health-check.sh && grep -q 'claude -p' bin/vault-health-check.sh && echo "script ready: bin/vault-health-check.sh"
   echo "0 9 1 * * /Users/you/bin/vault-health-check.sh" | grep -Eq '^0 9 1 \* \* ' && echo "cron OK: 1st of month at 09:00"

2. 2

   Schedule and run (the Claude step, not checked by CI)

   Add `0 9 1 * * ~/bin/vault-health-check.sh` to crontab. Claude Code, with MCPVault registered, leans on get_vault_stats / search_notes / get_frontmatter / get_notes_info to spot the rot and writes a checklist. The audit runs a model, so CI doesn't run it.