MCPVault

A security-first password manager for macOS that AI assistants can use through the Model Context Protocol, with every client on its own scoped token.

What it does

MCPVault (mcp-vault) lets any MCP client over stdio, or a remote MCP client over HTTP through an authenticated tunnel, do the following:

• generate strong passwords on demand,

• create and store a credential during a website signup and hand the new password back to the caller only,

• fill a login by site, with subdomains matching their parent domain,

• list and search entries without ever exposing secrets,

• reveal a password explicitly, or deliver it straight to the macOS clipboard with a 30-second auto-clear.

Everything is encrypted at rest with a master key that lives only in the macOS Keychain. Each client gets its own token with read / write / reveal / delete permissions, and every action is written to a secret-free audit log.

Related MCP server: Coffer MCP

Features

• 🔐 AES-256-GCM encryption of the whole vault (sites, usernames, notes too), with HKDF-SHA256 subkeys

• 🗝️ macOS Keychain master key (never in a file, env var, or process argv); on Linux servers a root-only key file / systemd credential (docs)

• 🎟️ Per-client tokens and profiles: permissions, allowed transports, optional site allowlist, clipboard flag

• 🧾 Audit log of every call (client, action, entry id, outcome); never secrets

• 🎲 CSPRNG password generator: default 24 chars, 8–256, configurable charset, guaranteed class coverage

• 📋 Concealed clipboard delivery (skipped by clipboard managers) with auto-clear after 30 s

• 🔌 stdio transport for local clients plus an optional loopback-only Streamable HTTP transport (bearer auth, disabled by default)

• 🔁 Crash-safe master-key rotation and passphrase-encrypted backups (scrypt + AES-256-GCM)

• 🧩 Official MCP TypeScript SDK (@modelcontextprotocol/sdk 1.32.1, pinned): McpServer.registerTool with strict zod schemas, StdioServerTransport, StreamableHTTPServerTransport

• 📦 Two pinned runtime dependencies (the SDK and zod); crypto, HTTP and storage use the Node.js standard library

• 🔒 700/600 file permissions, atomic writes, cross-process locking

Security model

Threat model and limitations

MCPVault protects secrets at rest, enforces least privilege between MCP clients, and keeps secrets out of logs, files and process arguments. It does not defend against code already running as your macOS user with shell access: such code can read the Keychain item via /usr/bin/security. Passwords revealed with deliver: "return" enter the AI model's context; prefer deliver: "clipboard". Full details: docs/threat-model.md.

Always-on server

deploy/ holds a hardened systemd setup (vault on 127.0.0.1, Cloudflare named tunnel, nightly encrypted backups, per-agent bearer tokens without delete rights). See docs/runbooks/server-deployment.md and docs/clients/remote.md.

Quick start

git clone https://github.com/smSamani/MCPVault.git mcp-vault && cd mcp-vault
npm install && npm test               # build + unit and SDK integration tests
node dist/src/cli.js init             # master key -> Keychain, empty vault in ~/.mcp-vault
node dist/src/cli.js client add my-client --perms read,write,reveal --transport stdio   # prints a token once
npm run smoke                         # optional end-to-end MCP test with a dummy entry

Then ask your assistant: "Create a login for example.com with username me@example.com and copy the password to my clipboard."

Install

Requirements: macOS, Node.js ≥ 20. Runtime dependencies (pinned): @modelcontextprotocol/sdk@1.32.1, zod@4.6.7. Dev: typescript, @types/node.

npm install
npm run build                       # outputs dist/
node dist/src/cli.js init

Optional convenience wrapper, so you can type mcp-vault ...:

cat > ~/.local/bin/mcp-vault <<'EOF'
#!/bin/sh
exec /ABSOLUTE/PATH/TO/node /ABSOLUTE/PATH/TO/mcp-vault/dist/src/cli.js "$@"
EOF
chmod 755 ~/.local/bin/mcp-vault

Data lives in ~/.mcp-vault/ (vault.enc, clients.json, config.json, audit.log). Override the location with MCP_VAULT_HOME. → docs/runbooks/install.md

Tools reference

Every secret-returning tool accepts deliver: "return" | "clipboard". With clipboard, the secret is not included in the result (local stdio clients only).

Connecting clients

Local MCP clients (stdio)

mcp-vault client add my-client --perms read,write,reveal,delete --transport stdio   # prints the token once

Add the following to the MCP configuration of any stdio-capable client and restart it:

{
  "mcpServers": {
    "mcp-vault": {
      "command": "/ABSOLUTE/PATH/TO/node",
      "args": ["/ABSOLUTE/PATH/TO/mcp-vault/dist/src/cli.js", "serve"],
      "env": { "MCP_VAULT_TOKEN": "<token>" }
    }
  }
}

→ docs/clients/stdio-clients.md

Remote assistants (e.g. Aryan / Grok Bot) over authenticated HTTP

The HTTP transport is off by default and only ever listens on 127.0.0.1. Reaching it remotely requires a tunnel that you set up.

mcp-vault client add aryan --transport http --perms read,reveal --sites example.com --no-clipboard  # token printed once
mcp-vault http enable --port 8765 --allowed-host <public-hostname>
mcp-vault serve-http                 # http://127.0.0.1:8765/mcp

Expose it in this order of preference:

1. Tailscale Serve (tailnet-only, never public). Best if the remote machine can join your tailnet.

2. Cloudflare Tunnel + Cloudflare Access (Service Auth token + IP rule) in front of the bearer token, giving two independent layers. See examples/cloudflared-config.example.yml.

3. Tailscale Funnel (public, bearer token only): short tests only.

The remote client sends Authorization: Bearer <token>. Clipboard delivery is never available over HTTP. → docs/clients/aryan.md · docs/transports/http.md

Retrieving a stored password

• Via your assistant: "Get my github.com login" → get_login_for_site, ideally with deliver: "clipboard".

• Yourself, in Terminal (passwords are never printed):

  mcp-vault list github                 # metadata only
  mcp-vault copy github.com --user me   # clipboard, auto-clears in 30 s
  mcp-vault add example.com me          # generate + store + copy
  mcp-vault audit --tail 20

→ docs/runbooks/retrieve-password.md · docs/cli.md

Backup and key rotation

mcp-vault backup ~/Documents/vault.mcpvault-backup   # passphrase-encrypted (scrypt N=2^17 + AES-256-GCM)
mcp-vault restore ~/Documents/vault.mcpvault-backup  # merge entries back by id
mcp-vault rotate-key                                 # new master key, re-encrypt everything, crash-safe
mcp-vault client rotate-token <name>                 # rotate a client's token

A passphrase backup is independent of the Keychain, so it survives losing the Mac. vault.enc alone is useless without the Keychain item. → docs/runbooks/backup-and-rotate.md

Architecture

client ─stdio (env token)──────────▶ StdioServerTransport ─┐
remote ─HTTPS tunnel─▶ 127.0.0.1 checks + Bearer auth ─▶ StreamableHTTPServerTransport ─┤
                                                         ▼
                       McpServer (per principal, only permitted tools, zod schemas)
                                                         ▼
                       callTool → permission → validate → handler → audit
                                                         ▼
                       AES-256-GCM vault  ·  macOS Keychain master key

Details: docs/architecture.md

Documentation

Start at docs/index.md. Full documentation is an Open Knowledge Format (OKF v0.2) bundle in docs/. Automated agents should read AGENTS.md first.

Roadmap

• Gate the master key behind a code-signed helper with Touch ID / user-presence confirmation

• Per-tool rate limits and an optional "confirm every reveal" mode

• Tamper-evident (hash-chained) audit log with rotation

• TOTP (2FA) secrets with code generation

• Passphrase / diceware generation mode

• Import from CSV exports (1Password, Bitwarden, browsers)

• Optional OAuth 2.1 for the HTTP transport

• Linux support (libsecret) for running the vault off-Mac

Limitations

macOS only. It is a single-user vault with no sync. The HTTP transport is stateless JSON (no SSE) and requires a client that can send an Authorization header. The Node path is pinned at registration time. See docs/threat-model.md.

Security

Please report vulnerabilities privately. See SECURITY.md.

License

MIT