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

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

• Vault token for authentication

Quick Start with Docker Compose

The easiest way to get started is using the included docker-compose.yml which sets up both Vault (in dev mode) 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

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)

Using with MCP Clients

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Note:

• Replace your-vault:8200 with your Vault server address

• Replace your-vault-token with your Vault authentication token

Migrating from local builds: If you previously built the image locally as vault-mcp, you can:

• Use pre-built images by updating the image name to ghcr.io/kelleyblackmore/vault-mcp:latest, or

• Continue using your local image by keeping the image name as vault-mcp

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