Skip to main content
Glama
kelleyblackmore

Vault MCP Server

by kelleyblackmore
OverviewSchemaRelated ServersScoreDiscussions
Remote

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

Related MCP server: Vault MCP Server (mschuchard)

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):

.\setup.ps1

macOS/Linux (Bash):

./setup.sh

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:

# 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

MCP Client Setup

Cursor IDE

Step 1: Copy the configuration

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

Windows:

# Create directory if it doesn't exist
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.cursor"

# Copy the config file
Copy-Item -Path "configs\mcp_config.json" -Destination "$env:USERPROFILE\.cursor\mcp.json"

macOS/Linux:

# Create directory if it doesn't exist
mkdir -p ~/.cursor

# Copy the config file
cp configs/mcp_config.json ~/.cursor/mcp.json

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:

Use vault_read to read the secret at path secret/data/test

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:

# Location: %APPDATA%\Claude\claude_desktop_config.json
Copy-Item -Path "configs\mcp_config.json" -Destination "$env:APPDATA\Claude\claude_desktop_config.json"

macOS:

# Location: ~/Library/Application Support/Claude/claude_desktop_config.json
cp configs/mcp_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

Linux:

# Location: ~/.config/claude-desktop/claude_desktop_config.json
cp configs/mcp_config.json ~/.config/claude-desktop/claude_desktop_config.json

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:

# 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-compose build vault-mcp
# Or
docker build -t vault-mcp-vault-mcp:latest .

Running the Container

With Docker Run

docker run -it --rm \
  -e VAULT_ADDR=http://host.docker.internal:8200 \
  -e VAULT_TOKEN=myroot \
  vault-mcp-vault-mcp:latest

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)

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:

{
  "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
├── configs/              # MCP configuration files
│   ├── mcp_config.json   # MCP client configuration (Cursor, Claude Desktop)
│   └── vault-catalog.yaml # Docker Desktop MCP Toolkit catalog
├── docs/                 # Documentation files
├── 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
├── setup.ps1            # Setup script for Windows (PowerShell)
├── setup.sh             # Setup script for macOS/Linux (Bash)
├── 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

Available Tools

4 tools
vault_deleteC

Delete a secret from Vault at the specified path

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe path to delete the secret from (e.g., 'secret/data/myapp')

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool deletes a secret, implying a destructive mutation, but doesn't mention critical aspects like whether deletion is permanent, requires specific permissions, has side effects (e.g., affecting other paths), or what happens on success/failure. This leaves significant gaps for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, direct sentence with zero waste—it states the action, resource, and key input concisely. It's front-loaded and efficiently communicates the core purpose without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral traits (e.g., permanence, permissions), expected outcomes, or error handling. Given the complexity and risk of deletion, more context is needed to guide safe and effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, with the single parameter 'path' fully documented in the schema (including an example). The description adds no additional meaning beyond the schema's details, such as path format constraints or deletion scope. Baseline 3 is appropriate since the schema handles parameter documentation adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Delete') and resource ('a secret from Vault'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like vault_list or vault_write, which would require mentioning it removes data rather than listing or creating it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like vault_list or vault_write. It lacks context about prerequisites (e.g., needing an existing secret) or exclusions (e.g., not for reading data), leaving the agent to infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_listB

List secrets at the specified path in Vault

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe path to list secrets from (e.g., 'secret/metadata')

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but only states the basic operation. It doesn't disclose whether this is a read-only operation (implied but not stated), what permissions are required, whether it returns metadata or just names, pagination behavior, error conditions, or rate limits. For a Vault operation with zero annotation coverage, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action ('List secrets') and includes essential context ('at the specified path in Vault'). Every element earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a Vault secrets listing tool with no annotations and no output schema, the description is insufficient. It doesn't explain what format the listing returns (keys, metadata, recursive listing), whether it requires specific authentication, or how it handles empty paths or permissions errors. The agent lacks crucial operational context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with the path parameter fully documented in the schema. The description adds minimal value beyond the schema by reinforcing that the path is 'specified' and mentioning Vault context. This meets the baseline 3 for high schema coverage where the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('List') and resource ('secrets at the specified path in Vault'), making the purpose immediately understandable. It distinguishes from siblings like vault_read (which reads secret values) and vault_write/vault_delete (which modify data). However, it doesn't explicitly mention that this lists secret names/keys rather than values, which would make it a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context through 'at the specified path' and the sibling tools provide natural alternatives, but there's no explicit guidance about when to use this versus vault_read or how it differs from vault_read (which retrieves secret values). The agent must infer usage patterns from tool names alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_readC

Read a secret from Vault at the specified path

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe path to read the secret from (e.g., 'secret/data/myapp')

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool reads a secret, implying a read-only operation, but doesn't clarify critical aspects like authentication requirements, rate limits, error conditions (e.g., if the path doesn't exist), or what the output looks like (e.g., secret data format). This is a significant gap for a tool interacting with a secure system like Vault.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action ('Read a secret'), making it easy to parse. Every part of the sentence contributes to understanding, with no wasted verbiage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of interacting with Vault (a secure secret management system), the description is incomplete. There are no annotations to cover behavioral traits, no output schema to explain return values, and the description lacks details on authentication, error handling, or output format. For a tool with security implications, this leaves too many gaps for reliable agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the 'path' parameter well-documented in the schema itself (including an example). The description adds minimal value by mentioning 'the specified path' but doesn't provide additional context beyond what the schema already covers, such as path format constraints or Vault-specific nuances. Baseline 3 is appropriate given the high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Read') and resource ('a secret from Vault'), making the purpose immediately understandable. It specifies the target ('at the specified path'), which helps distinguish it from other operations like listing or writing. However, it doesn't explicitly differentiate from sibling tools like vault_list (which might list paths rather than read secrets).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like vault_list or vault_write. It mentions the path parameter but doesn't explain prerequisites (e.g., authentication needs) or scenarios where reading is appropriate over other operations. This leaves the agent without context for tool selection among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_writeC

Write a secret to Vault at the specified path

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe path to write the secret to (e.g., 'secret/data/myapp')
dataYesThe secret data to write as a JSON object

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. While 'Write' implies a mutation operation, it doesn't specify whether this creates new secrets or updates existing ones, what permissions are required, whether the operation is idempotent, or how errors are handled. This leaves significant behavioral gaps for a write operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded with the core action, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a write operation with no annotations and no output schema, the description is insufficiently complete. It doesn't address critical context like what happens on success/failure, whether existing secrets are overwritten, authentication requirements, or return values. The agent lacks necessary operational understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, both parameters are already documented in the schema. The description adds no additional semantic context beyond what's in the schema descriptions, such as path format conventions or data structure expectations. The baseline score of 3 reflects adequate but minimal value addition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Write a secret') and target resource ('to Vault at the specified path'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like vault_read or vault_delete, which would require mentioning this is for creating/updating secrets rather than reading or deleting them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like vault_read or vault_delete. There's no mention of prerequisites, use cases, or exclusions, leaving the agent with no contextual decision-making information beyond the basic action.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose targeting a specific CRUD operation: delete, list, read, and write. There is no overlap or ambiguity between these actions, making it easy for an agent to select the correct tool for any secret management task.

Naming Consistency5/5

All tool names follow a perfect and consistent pattern: 'vault_' prefix followed by a verb (delete, list, read, write). This uniformity makes the tool set predictable and easy to understand at a glance.

Tool Count5/5

With 4 tools, this server is well-scoped for its purpose of Vault secret management. Each tool earns its place by covering essential CRUD operations without bloat, making the set concise and effective for the domain.

Completeness5/5

The tool set provides complete CRUD/lifecycle coverage for secret management: write (create), read (retrieve), list (browse), and delete (remove). There are no obvious gaps, ensuring agents can handle all core workflows without dead ends.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Vault MCP Bridge

    geopolitis
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables secure management of agent-scoped secrets in HashiCorp Vault through MCP protocol. Provides per-agent namespacing, multiple authentication methods (API key, JWT, mTLS), and optional encryption/decryption capabilities with built-in rate limiting.
    3

  • Vault MCP Server (mschuchard)

    mschuchard
    A
    license
    Not graded
    quality
    B
    maintenance
    A third-party MCP server for interacting with HashiCorp Vault to manage ACL policies, audit devices, and secret engines like KV v2, PKI, and Transit. It provides tools for system backend administration and includes prompts for generating security policy configurations.
    MIT

  • HashiCorp Vault MCP Server

    rccyx
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables language models to securely manage HashiCorp Vault secrets and ACL policies through the Model Context Protocol. It supports automated secret rotation, discovery, and HCL policy authoring using a suite of dedicated tools and resources.
    11
    6
    MIT

  • vault-kv-mcp

    elisjetmax
    F
    license
    A
    quality
    C
    maintenance
    A read-only MCP server that provides tools to read, list, and inspect secrets from HashiCorp Vault's KV secrets engine (versions 1 and 2) using a Vault token.
    5

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kelleyblackmore/vault-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server