# vault-kv-mcp

A **read-only** MCP (Model Context Protocol) server that exposes the **HashiCorp Vault KV secrets engine** (versions 1 and 2) as tools. Every tool performs only non-destructive reads — there are no write, delete, or destroy operations. It authenticates with a Vault token and speaks MCP over **stdio**, so it works with local MCP clients such as Claude Desktop.

## Tools (all read-only)

| Tool | Description |
|------|-------------|
| `vault_kv_read` | Read a secret (latest or a specific KV v2 version). |
| `vault_kv_list` | List keys / sub-folders under a path. |
| `vault_kv_read_metadata` | KV v2: read version history and metadata. |
| `vault_list_kv_mounts` | Discover available secret mounts and their KV versions. |
| `vault_health` | Check Vault server health / connectivity. |

KV v1 vs v2 is auto-detected per mount when `kv_version` is not supplied (falling back to v2).

For defense in depth, pair this with a Vault token whose policies grant only `read`/`list` capabilities on the relevant paths.

## Configuration

Set these environment variables (see `.env.example`):

- `VAULT_ADDR` — Vault base URL (default `http://127.0.0.1:8200`)
- `VAULT_TOKEN` — **required** Vault token, sent as the `X-Vault-Token` header
- `VAULT_NAMESPACE` — optional, for Vault Enterprise / HCP Vault
- `VAULT_SKIP_VERIFY` — optional, set `true` to skip TLS verification (dev only)

The token only needs policies granting access to the KV paths you intend to use.

## Build

```bash
npm install
npm run build
```

## Run / test with the MCP Inspector

```bash
VAULT_ADDR=http://127.0.0.1:8200 VAULT_TOKEN=hvs.xxxx npm run inspector
```

## Use with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "vault-kv": {
      "command": "node",
      "args": ["/absolute/path/to/vault-mcp/dist/index.js"],
      "env": {
        "VAULT_ADDR": "http://127.0.0.1:8200",
        "VAULT_TOKEN": "hvs.your-token-here"
      }
    }
  }
}
```

## Quick local Vault for testing

```bash
vault server -dev          # prints a Root Token and unseal info
export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_TOKEN=<root-token-from-output>
vault kv put secret/demo username=app password=s3cr3t
```

Then ask your MCP client to read `secret/demo`.

## Security notes

- The server only ever reads from Vault; it never writes, deletes, or destroys secrets.
- The token is read only from the environment and never logged.
- Prefer a short-lived, least-privilege token (read/list only) over a root token.