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:

# Build and start services
docker-compose up -d

# Check logs
docker-compose logs -f vault-mcp

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:

# Pull the latest image
docker pull ghcr.io/kelleyblackmore/vault-mcp:latest

# Pull a specific version
docker pull ghcr.io/kelleyblackmore/vault-mcp:v1.0.0

The images are automatically built for multiple platforms:

• linux/amd64 (x86_64)
• linux/arm64 (ARM64/aarch64)

Building Locally

docker build -t vault-mcp .

Running the Container

With Docker Run

docker run -it \
  -e VAULT_ADDR=http://your-vault:8200 \
  -e VAULT_TOKEN=your-vault-token \
  vault-mcp

With Docker Compose

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

environment:
  VAULT_ADDR: http://vault:8200
  VAULT_TOKEN: your-token

Then run:

docker-compose up vault-mcp

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

{
  "mcpServers": {
    "vault": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "VAULT_ADDR=http://your-vault:8200",
        "-e",
        "VAULT_TOKEN=your-vault-token",
        "ghcr.io/kelleyblackmore/vault-mcp:latest"
      ]
    }
  }
}

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:

{
  "path": "secret/data/myapp"
}

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:

{
  "path": "secret/data/myapp",
  "data": {
    "username": "admin",
    "password": "secret123"
  }
}

vault_list

List secrets at a path in Vault.

Parameters:

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

Example:

{
  "path": "secret/metadata"
}

vault_delete

Delete a secret from Vault.

Parameters:

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

Example:

{
  "path": "secret/data/myapp"
}

Development

Local Development Setup

# Install dependencies
npm install

# Build the project
npm run build

# Run locally (requires Vault server)
VAULT_ADDR=http://localhost:8200 VAULT_TOKEN=myroot npm start

Project Structure

vault-mcp/
├── .github/
│   └── workflows/
│       └── docker-build-publish.yml  # CI/CD workflow for container builds
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript (generated)
├── Dockerfile           # Container definition
├── docker-compose.yml   # Docker Compose configuration
├── package.json         # Node.js dependencies
├── tsconfig.json        # TypeScript configuration
└── README.md           # This file

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