vault-mcp

A containerized Model Context Protocol (MCP) server for interacting with HashiCorp Vault. This server provides MCP tools for reading, writing, listing, and deleting secrets in Vault.

Features

• vault_read: Read secrets from Vault at a specified path

• vault_write: Write secrets to Vault at a specified path

• vault_list: List secrets at a specified path in Vault

• vault_delete: Delete secrets from Vault at a specified path

Prerequisites

• Docker and Docker Compose

• Docker Desktop 4.42.0+ with MCP Toolkit enabled (for Docker Desktop integration)

• HashiCorp Vault instance (can use the included dev server)

• Vault token for authentication

Quick Start

Option 1: Docker Desktop MCP Toolkit (Recommended)

Run the setup script to install and configure the server:

Windows (PowerShell):

macOS/Linux (Bash):

What the setup script does:

• Builds the Docker image if needed

• Starts Vault dev server

• Creates the MCP catalog in Docker Desktop

• Adds and enables the vault-mcp server

Configuration used:

• Catalog file: configs/vault-catalog.yaml

• Vault address: http://host.docker.internal:8200

• Vault token: myroot (dev mode)

After running the setup script, restart Docker Desktop to see the server in the "My Servers" section.

See docs/INSTALL_DOCKER_DESKTOP.md for detailed installation instructions.

Option 2: Docker Compose

Start both Vault and the MCP server:

This will start:

• A Vault dev server at http://localhost:8200 with root token myroot

• The vault-mcp server connected to the Vault instance

MCP Client Setup

Cursor IDE

Step 1: Copy the configuration

Copy configs/mcp_config.json to your Cursor MCP configuration file:

Windows:

macOS/Linux:

Step 2: Update the configuration (if needed)

Edit ~/.cursor/mcp.json (or %USERPROFILE%\.cursor\mcp.json on Windows) and update:

• VAULT_ADDR: Your Vault server address

• VAULT_TOKEN: Your Vault token

• Image name: Use vault-mcp-vault-mcp:latest if built locally

Step 3: Restart Cursor

Completely quit and restart Cursor for the changes to take effect.

Step 4: Test

In Cursor, try asking:

See docs/TEST_CURSOR_MCP.md for more testing instructions.

Claude Desktop

Copy the configuration from configs/mcp_config.json to your Claude Desktop configuration:

Windows:

macOS:

Linux:

Then restart Claude Desktop.

Building the Docker Image

Using Pre-built Images from GitHub Container Registry

Pre-built container images are automatically published to GitHub Container Registry:

The images are automatically built for multiple platforms:

• linux/amd64 (x86_64)

• linux/arm64 (ARM64/aarch64)

Building Locally

Running the Container

With Docker Run

With Docker Compose

Edit the docker-compose.yml file to configure your Vault connection:

Then run:

Configuration

The server is configured via environment variables:

• VAULT_ADDR: The Vault server address (default: http://127.0.0.1:8200)

• VAULT_TOKEN: The Vault authentication token (required)

Configuration files are located in the configs/ directory:

• configs/vault-catalog.yaml - Docker Desktop MCP Toolkit catalog configuration

• configs/mcp_config.json - MCP client configuration (Cursor, Claude Desktop)

Available Tools

vault_read

Read a secret from Vault.

Parameters:

• path (string, required): The path to read the secret from (e.g., secret/data/myapp)

Example:

vault_write

Write a secret to Vault.

Parameters:

• path (string, required): The path to write the secret to (e.g., secret/data/myapp)

• data (object, required): The secret data to write as a JSON object

Example:

vault_list

List secrets at a path in Vault.

Parameters:

• path (string, required): The path to list secrets from (e.g., secret/metadata)

Example:

vault_delete

Delete a secret from Vault.

Parameters:

• path (string, required): The path to delete the secret from (e.g., secret/data/myapp)

Example:

Development

Local Development Setup

Project Structure

CI/CD

The project uses GitHub Actions to automatically build and publish Docker images:

• On push to main: Builds and publishes the latest tag and a SHA-based tag

• On pull request: Builds the image to verify it compiles (does not publish)

• On version tags (e.g., v1.0.0): Builds and publishes version-specific tags (e.g., v1.0.0, v1.0, v1)

Images are published to GitHub Container Registry at ghcr.io/kelleyblackmore/vault-mcp.

Security Considerations

• Never hardcode Vault tokens in configuration files

• Use appropriate Vault policies to limit MCP server permissions

• For production use, replace the dev Vault server with a properly configured production instance

• Consider using Vault AppRole or Kubernetes auth instead of token-based auth

• Use secrets management tools to inject VAULT_TOKEN at runtime

License

MIT