# 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
```bash
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):**
```bash
npm start
```
**With Authentication:**
```bash
export MCP_AUTH_TOKEN="your-secure-token-here"
npm start
```
**With HTTPS:**
```bash
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:
```bash
Authorization: Bearer <your-token>
```
For detailed authentication setup, see [AUTHENTICATION.md](./AUTHENTICATION.md).
### Using with Gemini CLI
Add this configuration to your Gemini config file:
**MacOS**: `~/.config/gemini-cli/config.json`
**Without Authentication:**
```json
{
"mcpServers": {
"vault": {
"url": "http://localhost:3000/mcp",
"transport": "http",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream"
}
}
}
}
```
**With Authentication:**
```json
{
"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:**
```json
{
"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](./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`
```json
{
"mcpServers": {
"vault": {
"url": "http://localhost:3000/mcp",
"headers": {
"Authorization": "Bearer your-secure-token-here"
}
}
}
}
```
For more details, see [COPILOT_SETUP.md](./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
```json
{
"tool": "vault_kv_read",
"arguments": {
"path": "myapp/config",
"mount": "secret",
"version": 1
}
}
```
### Creating/Writing a Secret
```json
{
"tool": "vault_kv_create",
"arguments": {
"path": "myapp/config",
"mount": "secret",
"data": {
"username": "admin",
"password": "secret123",
"api_key": "abc-xyz-123"
}
}
}
```
### Listing Secrets
```json
{
"tool": "vault_kv_list",
"arguments": {
"mount": "secret",
"folder": "myapp"
}
}
```
### Deleting a Secret
```json
{
"tool": "vault_kv_delete",
"arguments": {
"path": "secret/data/myapp/config"
}
}
```
### Testing with cURL
```bash
# 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](./TESTING.md).
## Development
### Build
```bash
npm run build
```
### Watch Mode
```bash
npm run watch
```
## Vault Setup
For testing, you can run Vault in dev mode:
```bash
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](./AUTHENTICATION.md).
## Quick Start
1. **Clone and install:**
```bash
git clone <repository-url>
cd hashi-vault-mcp
npm install
```
2. **Configure environment:**
```bash
cp .env.example .env
# Edit .env with your Vault details
```
3. **Build and run:**
```bash
npm run build
npm start
```
4. **Test the server:**
```bash
curl http://localhost:3000/health
```
## Additional Documentation
- [Authentication Setup](./AUTHENTICATION.md) - Detailed guide for bearer token authentication and TLS
- [Gemini CLI Setup](./GEMINI_CLI_SETUP.md) - Configure Gemini CLI to use this server
- [Claude Desktop Setup](./COPILOT_SETUP.md) - Configure Claude Desktop integration
- [Testing Guide](./TESTING.md) - 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