Cosmicjedi/vault-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

• HashiCorp Vault API Docs
• TOTP Secrets Engine
• KV Secrets Engine v2
• MCP Protocol

📄 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.