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

npm install
npm run build

Run / test with the MCP Inspector

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:

{
  "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

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.