hashi-vault-mcp

rod-anami-kyndryl/hashi-vault-mcp

3.2

If you are the rightful owner of hashi-vault-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server for interacting with HashiCorp Vault using a Streamable HTTP API.

Tools
4
Resources
0
Prompts
0

HashiCorp Vault MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with HashiCorp Vault via Streamable HTTP API.

Features

This MCP server provides the following tools for Vault KV operations:

  • vault_kv_read: Read secrets from Vault at a specified path with optional version and mount point
  • vault_kv_create: Create/write secrets to Vault at a specified path
  • vault_kv_list: List secrets at a specified path in a mount point
  • vault_kv_delete: Delete the latest version of secrets from Vault at a specified path

Security Features

  • Optional Bearer Token Authentication: Protect your MCP endpoints with token-based authentication
  • TLS/HTTPS Support: Enable encrypted connections with custom certificates
  • CORS Configuration: Control cross-origin access to your server

Installation

npm install
npm run build

Prerequisites

This server uses the hashi-vault-js library to communicate with HashiCorp Vault. Make sure you have:

  • Node.js 18 or later
  • A running HashiCorp Vault server
  • A valid Vault authentication token

Configuration

The server supports the following environment variables:

Vault Configuration (Required)

  • VAULT_ADDR: The address of your Vault server (default: http://127.0.0.1:8200)
  • VAULT_TOKEN: Your Vault authentication token
  • VAULT_URL: Full Vault API URL (default: ${VAULT_ADDR}/v1)
  • VAULT_TIMEOUT: Request timeout in milliseconds (default: 5000)
  • VAULT_CACERT: Path to CA certificate for Vault TLS verification (optional)

MCP Server Configuration

  • MCP_PORT: The port for the MCP server API (default: 3000)

Security Configuration (Optional)

  • MCP_AUTH_TOKEN: Bearer token for API authentication (if not set, authentication is disabled)
  • MCP_TLS_ENABLED: Set to "true" to enable HTTPS (default: false)
  • MCP_TLS_KEY: Path to TLS private key (default: ./certs/mcp-server.key)
  • MCP_TLS_CERT: Path to TLS certificate (default: ./certs/mcp-server.crt)
  • MCP_TLS_CA: Path to CA certificate (default: ./certs/ca.crt)

See .env.example for a complete configuration template.

Usage

Running the Server

Basic (HTTP, no authentication):

npm start

With Authentication:

export MCP_AUTH_TOKEN="your-secure-token-here"
npm start

With HTTPS:

export MCP_TLS_ENABLED="true"
export MCP_TLS_KEY="./certs/mcp-server.key"
export MCP_TLS_CERT="./certs/mcp-server.crt"
npm start

The server will expose the following endpoints:

  • /health - Health check endpoint (unprotected)
  • /mcp - MCP endpoint for client connections (protected if MCP_AUTH_TOKEN is set)

Authentication

When MCP_AUTH_TOKEN is set, all requests to /mcp must include:

Authorization: Bearer <your-token>

For detailed authentication setup, see .

Using with Gemini CLI

Add this configuration to your Gemini config file:

MacOS: ~/.config/gemini-cli/config.json

Without Authentication:

{
  "mcpServers": {
    "vault": {
      "url": "http://localhost:3000/mcp",
      "transport": "http",
      "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

With Authentication:

{
  "mcpServers": {
    "vault": {
      "url": "http://localhost:3000/mcp",
      "transport": "http",
      "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
        "Authorization": "Bearer your-secure-token-here"
      }
    }
  }
}

With HTTPS:

{
  "mcpServers": {
    "vault": {
      "url": "https://localhost:3000/mcp",
      "transport": "http",
      "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
        "Authorization": "Bearer your-secure-token-here"
      }
    }
  }
}

For more details, see .

Note: Make sure the server is running before connecting with Gemini CLI.

Using with Claude Desktop

Add this configuration to Claude Desktop:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vault": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-token-here"
      }
    }
  }
}

For more details, see .

Using with Other MCP Clients

Connect to the endpoint at http://localhost:3000/mcp (or https:// if TLS is enabled) using any MCP-compatible client. The server supports both GET and POST requests with StreamableHTTPServerTransport.

Tool Examples

Reading a Secret

{
  "tool": "vault_kv_read",
  "arguments": {
    "path": "myapp/config",
    "mount": "secret",
    "version": 1
  }
}

Creating/Writing a Secret

{
  "tool": "vault_kv_create",
  "arguments": {
    "path": "myapp/config",
    "mount": "secret",
    "data": {
      "username": "admin",
      "password": "secret123",
      "api_key": "abc-xyz-123"
    }
  }
}

Listing Secrets

{
  "tool": "vault_kv_list",
  "arguments": {
    "mount": "secret",
    "folder": "myapp"
  }
}

Deleting a Secret

{
  "tool": "vault_kv_delete",
  "arguments": {
    "path": "secret/data/myapp/config"
  }
}

Testing with cURL

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your-token" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

For more examples, see .

Development

Build

npm run build

Watch Mode

npm run watch

Vault Setup

For testing, you can run Vault in dev mode:

vault server -dev

This will start Vault at http://127.0.0.1:8200 with a root token displayed in the output.

Security Notes

Vault Security

  • Never commit your VAULT_TOKEN to version control
  • Use appropriate Vault policies to restrict access
  • Consider using AppRole or other authentication methods for production
  • Ensure your Vault server uses TLS in production environments
  • Use VAULT_CACERT to verify Vault's TLS certificate

MCP Server Security

  • Enable Authentication: Set MCP_AUTH_TOKEN to protect your MCP endpoints
  • Use HTTPS: Enable MCP_TLS_ENABLED for encrypted connections in production
  • Generate Strong Tokens: Use openssl rand -hex 32 for authentication tokens
  • Rotate Tokens: Change authentication tokens regularly
  • Network Access: Use firewalls or reverse proxies to restrict access
  • Environment Security: Never commit .env files with real tokens
  • Certificate Management: Keep TLS certificates and keys secure (chmod 600)

For detailed security guidance, see .

Quick Start

  1. Clone and install:

    git clone <repository-url>
cd hashi-vault-mcp
npm install

  2. Configure environment:

    cp .env.example .env
# Edit .env with your Vault details

  3. Build and run:

    npm run build
npm start

  4. Test the server:

    curl http://localhost:3000/health

Additional Documentation

  • - Detailed guide for bearer token authentication and TLS
  • - Configure Gemini CLI to use this server
  • - Configure Claude Desktop integration
  • - Test scripts and troubleshooting

Troubleshooting

Connection Issues

  • Verify Vault is running: vault status
  • Check VAULT_ADDR matches your Vault server address
  • Ensure VAULT_TOKEN has appropriate permissions
  • For HTTPS Vault, set VAULT_CACERT to your CA certificate path

Authentication Errors

  • Verify MCP_AUTH_TOKEN matches between server and client
  • Check Authorization header format: Bearer <token>
  • Ensure token is set in client configuration

TLS/HTTPS Issues

  • Verify certificate files exist at configured paths
  • Check certificate file permissions
  • For self-signed certificates, clients may need to trust the CA or use -k flag

License

MIT