vault-mcp-server by Cosmicjedi - MCP Server

HashiCorp Vault MCP Server

A Model Context Protocol (MCP) server that provides secure access to HashiCorp Vault for credential management and TOTP code generation.

🚀 Features

Credential Management: Read, write, delete, and list secrets in KV v2 engine
TOTP Support: Generate, import, validate TOTP codes for 2FA
Vault Administration: Check status, enable engines, manage configurations
Secure by Design: Token-based auth, Docker secrets, masked outputs
Enterprise Ready: Supports namespaces for Vault Enterprise/HCP

📋 Prerequisites

Docker Desktop with MCP Toolkit enabled
Docker MCP CLI plugin (docker mcp command)
A running HashiCorp Vault server
Valid Vault authentication token

🛠️ Available Tools

Secret Management

check_vault_status - Check health and seal status
read_secret - Read secrets from KV v2 engine
write_secret - Write secrets with JSON data
delete_secret - Delete specific or all versions
list_secrets - List secrets at a path
list_secrets_engines - List enabled engines
enable_secrets_engine - Enable new engines

TOTP Management

create_totp_key - Generate new TOTP keys
import_totp_key - Import existing TOTP keys
get_totp_code - Generate current codes
validate_totp_code - Validate codes
list_totp_keys - List all TOTP keys
delete_totp_key - Remove TOTP keys

📦 Installation

Step 1: Clone and Build

git clone https://github.com/Cosmicjedi/vault-mcp-server.git
cd vault-mcp-server
docker build -t vault-mcp-server .

Step 2: Configure Secrets

# Set your Vault token
docker mcp secret set VAULT_TOKEN="your-vault-token"

# Set Vault server address
docker mcp secret set VAULT_ADDR="http://your-vault-server:8200"

# Optional: For Vault Enterprise/HCP
docker mcp secret set VAULT_NAMESPACE="admin"

Step 3: Add to MCP Catalog

Create ~/.docker/mcp/catalogs/custom.yaml:

version: 2
name: custom
displayName: Custom MCP Servers
registry:
  vault:
    description: "HashiCorp Vault integration for secure credential and TOTP management"
    title: "Vault"
    type: server
    dateAdded: "2025-01-24T00:00:00Z"
    image: vault-mcp-server:latest
    ref: ""
    tools:
      - name: check_vault_status
      - name: read_secret
      - name: write_secret
      - name: delete_secret
      - name: list_secrets
      - name: create_totp_key
      - name: import_totp_key
      - name: get_totp_code
      - name: validate_totp_code
      - name: list_totp_keys
      - name: delete_totp_key
      - name: enable_secrets_engine
      - name: list_secrets_engines
    secrets:
      - name: VAULT_TOKEN
        env: VAULT_TOKEN
        example: hvs.CAESIGZ3...
      - name: VAULT_ADDR
        env: VAULT_ADDR
        example: http://127.0.0.1:8200
      - name: VAULT_NAMESPACE
        env: VAULT_NAMESPACE
        example: admin
    metadata:
      category: integration
      tags:
        - security
        - credentials
        - secrets
        - totp
        - vault
      license: MIT
      owner: local

Step 4: Update Registry

Add to ~/.docker/mcp/registry.yaml under the registry: key:

registry:
  # ... existing servers ...
  vault:
    ref: ""

Step 5: Configure Claude Desktop

Edit Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Add custom catalog to args:

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "[YOUR_HOME]/.docker/mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ]
    }
  }
}

Step 6: Restart Claude Desktop

Quit and restart Claude Desktop to load the new tools.

🧪 Quick Test Setup

For testing, you can run Vault in dev mode:

# Start Vault in dev mode (INSECURE - testing only!)
docker run --cap-add=IPC_LOCK \
  -e 'VAULT_DEV_ROOT_TOKEN_ID=root' \
  -p 8200:8200 \
  -d --name=vault-dev \
  vault:latest

# Configure MCP secrets for dev vault
docker mcp secret set VAULT_TOKEN="root"
docker mcp secret set VAULT_ADDR="http://host.docker.internal:8200"

# Enable TOTP engine
docker exec vault-dev vault secrets enable totp

💬 Usage Examples

In Claude Desktop, try these commands:

"Check the status of my Vault server"
"List all secrets in the secret mount"
"Write API credentials to secret/myapp/api with data {"key": "abc123"}"
"Read the secret at secret/myapp/api"
"Generate a new TOTP key for GitHub with account user@example.com"
"Get the current TOTP code for GitHub"
"List all my TOTP keys"
"Enable a new KV secrets engine at path myapp"

🔒 Security Considerations

All secrets stored in Docker Desktop secrets
Never hardcode credentials
Use least-privilege Vault policies
Sensitive values are masked in outputs
Runs as non-root user in container

🛡️ Required Vault Permissions

path "secret/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
path "totp/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
path "sys/health" {
  capabilities = ["read"]
}
path "sys/mounts/*" {
  capabilities = ["read", "update"]
}

🐛 Troubleshooting

Tools Not Appearing

Verify Docker image built successfully
Check catalog and registry files
Ensure Claude Desktop config includes custom catalog
Restart Claude Desktop

Authentication Errors

Verify token with docker mcp secret list
Ensure token has required permissions
Check VAULT_ADDR is accessible
For HCP Vault, ensure VAULT_NAMESPACE is set

Connection Issues

Verify Vault is running and unsealed
Check network connectivity
Ensure TLS certificates are valid (if using HTTPS)

📖 Documentation

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

👤 Author

Created for the MCP community to enable secure Vault integration by Cosmicjedi.