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

Clone and install:

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

Configure environment:

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

Build and run:
```
npm run build
npm start
```
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

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

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

Clone and install:

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

Configure environment:

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

Build and run:
```
npm run build
npm start
```
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