#Install

Three commands and you're live. mcpvault ships as a single Node CLI on npm. Node 20 or newer is required.

#1. Install the CLI

bash
npm install -g @elraian/mcpvault

This puts mcpvault on your PATH globally. Aliases mvault and mcp-vault resolve to the same binary if you have muscle memory.

#Platform notes

macOS / Linux: requires Node 20+. If npm complains about permissions, you almost certainly have a system Node. Fix with nvm or brew install node.

Windows: PowerShell 7 recommended. The vault uses DPAPI for keyring caching; no extra setup. If mcpvault is not on PATH after install, run npm config get prefix and add that directory to your user PATH.

WSL: works the same as Linux. Make sure your Windows-installed clients (Cursor, Claude Desktop) also see WSL's PATH if you want to call mcpvault from a Windows-native client; usually easier to install mcpvault inside Windows directly.

#2. Initialise the vault

bash
mcpvault init

Prompts for a master password (twice), derives an AES-256-GCM key with Argon2id, and writes an empty encrypted vault to ~/.mcpvault/vault.enc. The master password is never written to disk. The derived session key is cached in your OS keyring (Keychain, DPAPI, or libsecret) so you only re-enter the password if you explicitly run mcpvault lock or sign out of the OS.

If you forget the master password, the vault is unrecoverable. There is no backdoor.

#3. Add accounts

bash
mcpvault add supabase
mcpvault add github
mcpvault add vercel
mcpvault add stripe

Each command prompts for a label (e.g. work, personal, acme-prod), a description (used by fuzzy search), and the token. Tokens are validated against the upstream API on save — wrong format or expired tokens fail loud, before they hit your vault. See Services for token URLs and scopes per provider.

You can add as many accounts per service as you want. Labels are alphanumeric + dashes.

#4. Wire it into your chat client

bash
mcpvault setup

Auto-detects installed clients (Claude Code, Claude Desktop, Cursor, Cline, Windsurf) and writes the right config file for each. Restart the client and the tools appear.

For clients mcpvault doesn't auto-handle (Continue, Zed, Codex CLI, Gemini CLI, VS Code Copilot Chat, ChatGPT Desktop), copy the JSON from Clients and paste it into the client's config file. One snippet, all clients.

#Verify

bash
mcpvault doctor

Prints vault status (locked / unlocked), account counts per service, OS keyring availability, and which detected clients have mcpvault wired up. If anything's red, Troubleshooting has the fix.

#Upgrade

#Check what you're on

bash
mcpvault --version

#Check what's available

bash
npm outdated -g @elraian/mcpvault

Prints Current, Wanted and Latest. If Latest is ahead of Current, there's a new release.

#Update

bash
npm install -g @elraian/mcpvault@latest

mcpvault also ships a built-in updater that wraps the same npm command and re-runs mcpvault setup afterward (so any client config changes in the new version land automatically):

bash
mcpvault update

#Channels

Stable is the default. To opt into pre-release builds (early features, faster bug fixes, more breakage):

bash
mcpvault update --channel dev

To switch back:

bash
mcpvault update --channel stable

mcpvault config get channel prints the channel currently in use.

#Pin to a specific version

For reproducible installs (CI, team projects):

bash
npm install -g @elraian/mcpvault@1.4.2

#Verify after update

bash
mcpvault --version
mcpvault doctor

doctor re-checks vault integrity, OS keyring availability, and every wired client's config. Anything red gets a one-line fix.

#Migrations

Vault file format is forward-compatible across minor versions — no migration step for routine updates. Major-version bumps (1.x → 2.x) ship a one-shot migration:

bash
mcpvault migrate

The CLI prints a clear "migration needed" notice on first run after a major upgrade. Migrations are non-destructive — your previous vault is backed up to ~/.mcpvault/vault.enc.bak before any rewrite. Restore with mcpvault migrate --rollback if anything goes sideways.

#Changelog

Per-release notes: github.com/Elraian/mcpvault/releases. Subscribe via the Watch → Custom → Releases dropdown on the repo to get email notifications.

#Uninstall

bash
npm uninstall -g @elraian/mcpvault
rm -rf ~/.mcpvault

On Windows: Remove-Item -Recurse -Force "$env:USERPROFILE\.mcpvault". The OS keyring entry is named mcpvault.session — remove it manually if you want full cleanup.