encrypted-vault-mcp

MCP server providing a local-first encrypted key-value vault. Store API keys, secrets, notes, or any string data under a PIN. AES-GCM 256-bit cipher, PBKDF2 (600k iterations, SHA-256) derived key. Zero cloud. Zero telemetry. Zero network.

Why

Storing secrets in plain text in chat history is bad. Pasting API keys into prompts is worse. This MCP gives the agent a vault: it can store a value once under a name, then later fetch it by name without you re-typing the secret.

• AI agent can hold long-lived secrets safely between chats
• You unlock once per session with a PIN
• All data stays on the machine as encrypted bytes
• Wrong PIN = wrong key = nothing decrypts (AES-GCM auth tag fails)

Install

npm install -g encrypted-vault-mcp

Or npx:

npx encrypted-vault-mcp

Use with Claude Desktop

Add to claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "vault": {
      "command": "npx",
      "args": ["-y", "encrypted-vault-mcp"]
    }
  }
}

Restart Claude Desktop. First time:

"Use vault to init with pin 1234"

Then any time:

"Unlock vault with pin 1234, then store my-openai-key as sk-..."

"Fetch my-openai-key"

"List vault keys"

Tools

| Tool | Args | Description | |---|---|---| | init | pin | Create a new vault file with this PIN. Fails if one already exists. | | unlock | pin | Derive key from PIN. Required before store/fetch/list/remove. | | lock | — | Clear key from memory. | | store | key, value | Encrypt + save under name. | | fetch | key | Decrypt + return value. | | list | — | List all key names. Values stay encrypted on disk. | | remove | key | Delete an item. | | change_pin | old_pin, new_pin | Rotate PIN. Re-encrypts everything with new key. | | status | — | Show whether vault exists / is unlocked / path / item count. |

Crypto

• Cipher: AES-256-GCM (authenticated encryption — wrong PIN = decryption fails cleanly)
• Key derivation: PBKDF2-HMAC-SHA256, 600,000 iterations (OWASP 2023 recommendation), 16-byte salt
• IV: 96-bit random per encryption (NIST SP 800-38D)
• PIN verification: separate PBKDF2 hash with its own salt; the PIN itself is never persisted
• File permissions: vault file is written with mode 0o600 (owner read/write only)

Storage location

Default: ~/.encrypted-vault-mcp/vault.json

Override:

{
  "mcpServers": {
    "vault": {
      "command": "npx",
      "args": ["-y", "encrypted-vault-mcp"],
      "env": { "VAULT_PATH": "/secure/drive/my-vault.json" }
    }
  }
}

File format

{
  "version": 1,
  "salt": "<base64, 16 bytes>",       // for PBKDF2 key derivation
  "pinSalt": "<base64, 16 bytes>",    // separate salt for PIN verification
  "pinHash": "<base64, 32 bytes>",    // PBKDF2 hash of PIN (for verify only)
  "items": {
    "my-openai-key": {
      "iv": "<base64, 12 bytes>",
      "ciphertext": "<base64>",
      "tag": "<base64, 16 bytes>"    // GCM auth tag
    }
  }
}

Threat model

| Threat | Protected? | |---|---| | Disk read by attacker without PIN | ✅ items unrecoverable without PIN | | Wrong PIN | ✅ AES-GCM auth fails, no data leaked | | PIN brute-force | ⚠️ 600k PBKDF2 iterations slow it; use a real password for high-value secrets | | Process memory dump while unlocked | ❌ key sits in memory between unlock and lock — lock when done | | Malicious MCP client | ❌ if the agent itself is hostile, it can call fetch on whatever it wants — only run trusted agents |

Local development

git clone https://github.com/KhushalB25/encrypted-vault-mcp.git
cd encrypted-vault-mcp
npm install
npm run build
npm start

Inspect:

npx @modelcontextprotocol/inspector node dist/index.js

Author

Khushal Bhandari · GitHub

License

MIT