# vault-mcp

MCP server that exposes secrets from your OS keychain (or an AES-256-GCM encrypted file) as MCP tools. Secrets are returned directly in tool results and **never appear in conversation messages**.

## Tools

| Tool | Description |
|---|---|
| `get_secret(key)` | Read a secret value from the vault |
| `set_secret(key, value)` | Store a secret in the vault |
| `list_secrets()` | List stored key names — values are never returned |

## Quick start

```bash
# Install deps
cd vault-mcp && npm install

# Walk through adding a first secret and get your config block
npx vault-mcp init
# (on Linux without libsecret, set passphrase first)
# export VAULT_MCP_PASSPHRASE="my-strong-passphrase"
# npx vault-mcp init
```

The `init` command prints a JSON block to paste into `claude_desktop_config.json` (Claude Desktop) or `.claude/settings.json` (Claude Code).

## Backends

### OS Keychain (keytar) — recommended on macOS / Windows

When `keytar` installs successfully and `libsecret` is available, secrets are stored in the OS keychain (Keychain Access on macOS, Credential Manager on Windows, Secret Service on Linux).

No environment variable needed.

### AES-256-GCM file vault — Linux CI / containers

If `keytar` is unavailable, vault-mcp falls back to `~/.vault-mcp/vault.json`. Each value is encrypted with AES-256-GCM using a key derived via scrypt from your passphrase.

```bash
export VAULT_MCP_PASSPHRASE="my-strong-passphrase"
```

Add this env var to your MCP server config (see `init` output).

## Other CLI commands

```bash
vault-mcp set MY_SECRET "value"   # store without interactive prompt
vault-mcp list                     # print stored key names
vault-mcp server                   # start MCP server (used by config block)
```

## MCP config example (file vault)

```json
{
  "mcpServers": {
    "vault-mcp": {
      "command": "node",
      "args": ["/path/to/vault-mcp/src/server.js"],
      "env": {
        "VAULT_MCP_PASSPHRASE": "my-strong-passphrase"
      }
    }
  }
}
```