mcpvault
Install
← back to mcpvault
Docs menu+

Back up the vault, restore on a new machine, sync between machines.

#Backup & sync

The vault is one file: ~/.mcpvault/vault.enc. That makes backup trivial. Sync is also possible — with caveats.

#What to back up

text
~/.mcpvault/
├── vault.enc       # YOU NEED THIS — the encrypted credentials
├── active.json     # nice-to-have — preserves which label is active per service
└── vault.log       # optional — append-only audit log

The OS keyring entry (mcpvault.session) is not worth backing up. It's a cache of the derived key, machine-bound. New machine → re-enter master password → keyring re-populates.

You also need to remember (or store separately) your master password. Without it, the vault file is unrecoverable. There is no backdoor.

#Manual backup

bash
# macOS / Linux
cp -a ~/.mcpvault ~/Backups/mcpvault-$(date +%Y%m%d)

# Windows (PowerShell)
$ts = Get-Date -Format "yyyyMMdd"
Copy-Item -Recurse "$env:USERPROFILE\.mcpvault" "$env:USERPROFILE\Backups\mcpvault-$ts"

The vault file is encrypted, so the backup is safe to drop into iCloud, Dropbox, OneDrive, S3, etc. without further encryption — but don't symlink the live ~/.mcpvault folder into a sync drive (see "Don't symlink" below).

#Restore on the same machine

bash
mcpvault lock
cp ~/Backups/mcpvault-20260601/vault.enc ~/.mcpvault/vault.enc
mcpvault unlock                    # prompts for master password
mcpvault status

#Move to a new laptop

  1. 1On the old machine: copy ~/.mcpvault/vault.enc to a USB key, encrypted backup, or 1Password Items.
  2. 2On the new machine:

``bash npm install -g @elraian/mcpvault mkdir -p ~/.mcpvault cp /path/to/backup/vault.enc ~/.mcpvault/vault.enc mcpvault unlock # prompts for master password mcpvault setup # wire mcpvault into installed clients ``

  1. 1Verify with mcpvault status and mcpvault list.

That's it. No re-adding accounts.

#Sync between active machines

There are three sane options. All of them keep the vault file as the single source of truth.

#1. 1Password Items (recommended)

Store vault.enc as a file attachment in a 1Password Item. On each machine, when you change the vault, re-upload. Pull the file down on other machines as needed:

bash
op read "op://Private/mcpvault/vault.enc" > ~/.mcpvault/vault.enc
mcpvault unlock

Pros: encrypted-at-rest already, version history in 1Password, no live sync conflicts. Cons: manual.

#2. git-crypt (for the truly devops-brained)

Keep ~/.mcpvault as a git repo with git-crypt protecting the vault file. Push and pull as you would any code repo.

bash
cd ~/.mcpvault
git init
git-crypt init
echo "vault.enc filter=git-crypt diff=git-crypt" >> .gitattributes
git add . && git commit -m "initial"
git remote add origin <your-private-repo>
git push -u origin main

On the new machine:

bash
git-crypt unlock
mcpvault unlock

Pros: full version history, conflict detection. Cons: setup overhead, easy to forget to push.

#3. Encrypted backup tool (Restic, Borg, rsync.net)

Standard encrypted backup workflows. Restore on demand.

#Don't symlink

A frequently-suggested but bad idea: symlink ~/.mcpvault into Dropbox / iCloud / Google Drive.

bash
# DON'T DO THIS
ln -s ~/Dropbox/mcpvault ~/.mcpvault

Why not:

  • Concurrent writes corrupt `active.json`. Two machines saving at the same instant → file is half-written when sync triggers.
  • Sync conflicts on `vault.enc`. Cloud sync creates conflict copies (vault (raian's MacBook conflicted copy).enc) which mcpvault can't read.
  • OS-specific extended attributes lost. macOS adds .DS_Store and metadata that don't survive cross-platform sync.

If you want live sync, use the 1Password attachment or git-crypt approaches above. Both are explicit about when a sync happens.

#Restoring on a fresh machine after losing the master password

You can't. By design.

If you have a vault backup but no master password, the file is encrypted with a key that can't be derived without the password. Argon2id with m=64MiB, t=3 would take centuries to brute-force a strong password, and there is no "recovery key" baked in.

Workaround: on every working machine, re-add accounts with the new master password by re-running mcpvault init (which deletes the old vault) and mcpvault add for each service.

#Periodic backup with cron / Task Scheduler

Daily encrypted snapshot to S3:

bash
# crontab entry, runs daily at 03:00
0 3 * * * cp ~/.mcpvault/vault.enc /tmp/vault-$(date +\%Y\%m\%d).enc && \
          aws s3 cp /tmp/vault-$(date +\%Y\%m\%d).enc s3://my-backup-bucket/mcpvault/ && \
          rm /tmp/vault-*.enc

The file is already AES-256-GCM encrypted, so S3-side encryption is belt-and-suspenders. Lifecycle the bucket to delete snapshots older than 90 days.

#What sync gives up

The OS keyring entry stays per-machine. So on every machine you'll re-enter the master password once after restoring vault.enc — that's it.

The audit log (vault.log) is also per-machine. If you want a unified audit trail across machines, ship vault.log to your SIEM or an S3 bucket from each machine independently.

Backup & sync — mcpvault docs