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 AUTHENTICATION.md.

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 GEMINI_CLI_SETUP.md.

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 COPILOT_SETUP.md.

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 TESTING.md.

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 AUTHENTICATION.md.

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

• Authentication Setup - Detailed guide for bearer token authentication and TLS

• Gemini CLI Setup - Configure Gemini CLI to use this server

• Claude Desktop Setup - Configure Claude Desktop integration

• Testing Guide - 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