Vault MCP Server (TypeScript)

MCP server for fetching and comparing HashiCorp Vault secrets across pods.

Ported from the Java Spring Boot version to TypeScript for easier distribution and deployment.

Features

• List Pods: View all configured Vault pods
• List Secret Engines: Discover KV mounts and their versions
• List Secrets: Browse secret paths in a mount
• Get Secret: Retrieve secret values (with optional fingerprinting)
• Compare Secrets: Compare secrets across pods or environments
• Add Secret: Add new key-value pairs to existing secrets

Installation

npm install
npm run build

Configuration

Option 1: Using Config File (Recommended)

Create a config file anywhere on your local machine (e.g., C:\Users\your-username\.ssh\mcp-config.json or D:\configs\mcp-config.json):

{
  "VAULT_PODS": "pod1=https://vault-pod1.example.com|dev,pod2=https://vault-pod2.example.com|qa",
  "USERNAME": "your-username",
  "PASSWORD": "your-password"
}

Note: This same file can be used for both Vault MCP and Kubernetes MCP servers!

Then reference it in mcp_config.json using an absolute path:

{
  "mcpServers": {
    "vault-properties": {
      "command": "npx",
      "args": ["-y", "vault-properties-mcp"],
      "env": {
        "MCP_CONFIG_FILE": "C:\\Users\\your-username\\.ssh\\mcp-config.json",
        "VAULT_AUTH_PATH": "ldap",
        "VAULT_VERIFY_SSL": "false"
      }
    }
  }
}

The config file can be located anywhere:

• ✅ C:\Users\your-username\.ssh\mcp-config.json
• ✅ D:\my-configs\mcp-config.json
• ✅ C:\configs\mcp-config.json
• ✅ Any absolute path you prefer!

Option 2: Direct Environment Variables

{
  "mcpServers": {
    "vault-properties": {
      "command": "npx",
      "args": ["-y", "vault-properties-mcp"],
      "env": {
        "VAULT_PODS": "pod1=https://vault-pod1.example.com|dev,pod2=https://vault-pod2.example.com|qa",
        "VAULT_USERNAME": "your-username",
        "VAULT_PASSWORD": "your-password",
        "VAULT_AUTH_PATH": "ldap",
        "VAULT_VERIFY_SSL": "false"
      }
    }
  }
}

Config File Format

{
  "VAULT_PODS": "name=url|env[|namespace],name=url|env[|namespace],...",
  "USERNAME": "your-username",
  "PASSWORD": "your-password"
}

Format: name=url|env[|namespace] (using | as delimiter to avoid conflict with : in https://)

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Run
npm start

Available Tools

listPods

List all configured Vault pods with their environment and URL.

listSecretEngines

List all secret engine mounts on a pod.

Parameters:

• pod (required): Pod name

listSecrets

List secret keys/folders under a path.

Parameters:

• pod (required): Pod name
• mount (required): Mount path
• path (optional): Sub-path under the mount
• kvVersion (optional): "1", "2", or "auto"

getSecret

Read a secret with optional value fingerprinting.

Parameters:

• pod (required): Pod name
• mount (required): Mount path
• path (required): Secret path
• kvVersion (optional): "1", "2", or "auto"
• reveal (optional): Return plaintext values (default: false, returns SHA-256 fingerprints)

compareSecrets

Compare a secret across two pods.

Parameters:

• podA (required): First pod
• podB (required): Second pod
• mount (required): Mount path
• path (required): Secret path
• kvVersion (optional): "1", "2", or "auto"
• reveal (optional): Include plaintext for differences (default: false)

compareEnvs

Compare a secret across all dev vs qa pods.

Parameters:

• mount (required): Mount path
• path (required): Secret path
• kvVersion (optional): "1", "2", or "auto"

addSecret

Add a new secret at a path. Merges with existing data without deleting existing keys.

Parameters:

• pod (required): Pod name
• mount (required): Mount path
• path (required): Secret path
• secretData (required): Object with key-value pairs to add
• kvVersion (optional): "1", "2", or "auto"

Behavior:

• Only adds keys that don't already exist
• Existing keys are preserved and not overwritten
• Returns details about which keys were added and which were skipped

Security Notes

• Never commit credentials to version control
• Use environment variables for sensitive data
• The reveal parameter should be used carefully as it exposes plaintext secrets
• By default, all tools return SHA-256 fingerprints instead of plaintext values

License

MIT