Vault MCP Ext

保险库MCP服务器

Vault MCP服务器是 模型上下文协议（MCP） 提供与HashiCorp集成的服务器实现 用于管理机密和挂载的保险库。此服务器同时使用stdio和StreamableHTTP MCP通信的传输，使其与Claude for Desktop兼容 以及其他MCP客户端。

安全说明： 在此阶段，MCP服务器仅供本地使用。如果使用StreamableHTTP传输，请始终配置MCP_ALLOWED_ORIGINS环境变量，以限制仅访问受信任的源。这有助于防止DNS重新绑定攻击和其他跨源漏洞。

安全说明： 根据查询，MCP服务器可能会向MCP客户端和LLM公开某些Vault数据，包括Vault机密。不要将MCP服务器与不受信任的MCP客户端或LLM一起使用。

法律说明： 您对第三方MCP Client/LLM的使用仅受此类MCP/LLM使用条款的约束，IBM不对此类第三方工具的性能负责。IBM明确声明对第三方MCP客户/LLM不承担任何和所有保证和责任，并且可能无法提供支持来解决由第三方工具引起的问题。

注意： MCP服务器提供的输出和建议是动态生成的，可能因查询、模型和连接的MCP客户端而异。用户应在实施之前彻底审查所有输出/建议，以确保它们与组织的安全最佳实践、成本效益目标和合规要求保持一致。

特性

• 在Vault中创建新的挂载（KV v1、KV v2）
• 列出所有可用的挂载
• 删除挂载
• 为KV挂载写秘密
• 阅读KV挂载的秘密
• 列出路径下的所有秘密
• 删除完整的秘密或秘密的密钥
• 全面的HTTP中间件栈（CORS、日志、Vault上下文）
• 基于会话的Vault客户端管理
• 具有可配置输出的结构化日志记录

先决条件

• 转到1.24或更高版本（如果从源代码构建）
• 码头工人
• HashiCorp Vault服务器在本地或远程运行
• 具有适当权限的有效Vault令牌

设置

1. 克隆存储库：

   git clone https://github.com/hashicorp/vault-mcp-server.git
   cd vault-mcp-server

1. 构建二进制文件：

   make build

1. 运行服务器：

标准模式（默认）：

   ./vault-mcp-server
   # or explicitly
   ./vault-mcp-server stdio

HTTP模式：

   ./vault-mcp-server http --transport-port 8080
   # or using make
   make run-http

环境变量

可以使用环境变量配置服务器：

• VAULT_ADDR：Vault服务器地址（默认值： http://127.0.0.1:8200)
• VAULT_TOKEN：Vault身份验证令牌（必需）
• VAULT_NAMESPACE：Vault命名空间（可选）
• TRANSPORT_MODE：设置为 http 启用HTTP模式
• TRANSPORT_HOST：HTTP模式下要绑定的主机（默认值： 127.0.0.1)
• TRANSPORT_PORT：HTTP模式的端口（默认值： 8080)
• MCP_ENDPOINT：HTTP服务器终结点路径（默认值： /mcp)
• MCP_ALLOWED_ORIGINS：CORS允许的源列表，以逗号分隔（默认值： "")
• MCP_CORS_MODE：CORS模式： strict, development，或 disabled （默认值： strict)
• MCP_TLS_CERT_FILE：TLS证书文件的位置（例如。 /path/to/cert.pem)（默认值： "")
• MCP_TLS_KEY_FILE：TLS密钥文件的位置（例如。 /path/to/key.pem)（默认值： "")
• MCP_RATE_LIMIT_GLOBAL：全球费率限制（格式： rps:burst)（默认值： 10:20)
• MCP_RATE_LIMIT_SESSION：每次会话速率限制（格式： rps:burst)（默认值： 5:10)

HTTP模式配置

在HTTP模式下，可以通过多种方法（按优先级顺序）提供Vault配置：

• HTTP查询: VAULT_ADDR
• HTTP头处理模块: VAULT_ADDR, X-Vault-Token，以及 X-Vault-Namespace
• 环境变量：标准 VAULT_ADDR, VAULT_TOKEN，以及 VAULT_NAMESPACE 环境变量

中间件堆栈

HTTP服务器包括一个全面的中间件堆栈：

• CORS中间件：启用具有适当标头的跨源请求
• Vault上下文中间件：提取Vault配置并添加到请求上下文中
• 日志中间件：结构化HTTP请求日志记录

与Visual Studio代码集成

1. 在项目工作区根目录中，创建或打开 .vscode/mcp.json 配置文件。或者，要将MCP添加到用户配置中，请运行 MCP: Open User Configuration 命令，打开用户配置文件中的mcp.json文件。如果文件不存在，VS Code会为您创建它。

Streamable HTTP modeStdio mode

       {
           "inputs": [
           {
               "type": "promptString",
               "id": "vault_token",
               "description": "Vault Token",
               "password": true
           },
           {
               "type": "promptString",
               "id": "vault_namespace",
               "description": "Vault Namespace (optional)",
               "password": false
           }
           ],
           "servers": {
               "vault-mcp-server": {
                   "url": "http://localhost:8080/mcp?VAULT_ADDR=http://127.0.0.1:8200",
                   "headers": {
                       "X-Vault-Token": "${input:vault_token}",
                       "X-Vault-Namespace": "${input:vault_namespace}"
                   }
               }
           }
       }

       {
           "inputs": [
           {
               "type": "promptString",
               "id": "vault_token",
               "description": "Vault Token",
               "password": true
           },
           {
               "type": "promptString",
               "id": "vault_namespace",
               "description": "Vault Namespace (optional)",
               "password": false
           },
           {
               "type": "promptString",
               "id": "vault_addr",
               "description": "Vault Address (optional)",
               "password": false
           }
           ],
           "servers": {
           "vault-mcp-server": {
               "command": "docker",
               "args": [
                   "run",
                   "-i",
                   "--rm",
                   "-e", "VAULT_ADDR=${input:vault_addr}",
                   "-e", "VAULT_TOKEN=${input:vault_token}",
                   "-e", "VAULT_NAMESPACE=${input:vault_namespace}",
                   "hashicorp/vault-mcp-server"
                   ]
               }
           }
       }

1. 保存 mcp.json 文件。

1. 重新启动Visual Studio代码（或重新加载窗口）。

注： Visual Studio代码将提示您输入一次VAULT_TOKEN，并将其安全地存储在客户端中。

与Gemini扩展集成

为了安全起见，避免硬编码您的凭据，创建或更新 ~/.gemini/.env （其中~是您的主目录或项目目录）用于存储Vault地址、令牌和命名空间

# ~/.gemini/.env
VAULT_ADDR=your_vault_addr_here
VAULT_TOKEN=your_vault_token_here
VAULT_NAMESPACE=your_vault_namespace_here

安装扩展并运行Gemini

gemini extensions install https://github.com/hashicorp/vault-mcp-server
gemini

使用Docker

构建docker镜像：

make docker-build

使用自定义注册表构建映像：

make docker-build DOCKER_REGISTRY=your-registry.com

将映像推送到自定义注册表：

make docker-push DOCKER_REGISTRY=your-registry.com

运行Vault容器并获取根令牌：

docker network create mcp
docker run --cap-add=IPC_LOCK --name=vault-dev --network=mcp -p 8200:8200 hashicorp/vault server -dev
docker logs vault-dev

运行Vault MCP服务器：

docker run --network=mcp -p 8080:8080 -e VAULT_ADDR='http://vault-dev:8200' -e VAULT_TOKEN='' -e TRANSPORT_MODE='http' vault-mcp-server:dev

可用工具

装载管理工具

create_mount

在Vault中创建新的装载。

• type：挂载类型（例如“kv”、“kv2”、“pki”）
• path：创建挂载的路径
• description：（可选）安装说明

list_mount

列出Vault中的所有装载。

• 无需参数

删除_计数

删除Vault中的装载。

• path：要删除的装载路径

关键价值工具

list_secrets

列出Vault中特定路径下KV挂载中的秘密。

• mount：秘密发动机的安装路径
• path：（可选）列出机密的路径（默认为root）

删除密码

删除Vault中特定路径下KV挂载中的机密（或密钥）。

• mount：秘密发动机的安装路径
• path：要删除的密钥的路径
• key：（可选）要从整个密钥中删除的密钥名称（默认为删除整个密钥）

write_secret

将秘密写入Vault中的KV挂载。

• mount：秘密发动机的安装路径
• path：写秘密的完整路径
• key：密钥的密钥名称
• value：要存储的值

read_secret

从保险库中的KV支架中读取秘密。

• mount：秘密发动机的安装路径
• path：从中读取秘密的完整路径

read_kv_ccertificate_元数据

读取父路径下作为KV机密存储的证书，从每个证书中提取元数据，并返回聚合元数据。列出给定路径下的所有子路径（域名），从每个域读取证书文件（全链或全链.pem），解析证书，并提取元数据（通用名称、主题、颁发者、有效日期、SAN、密钥使用等）。

• mount：秘密引擎的挂载路径（例如，如果证书位于“secrets/acme/domain1/fullchain.pem”，则为“secrets”）
• path：存储证书机密的父路径（例如“acme”）

PKI工具

enable_pki

启用和配置PKI密钥引擎。

• path：PKI引擎的安装路径
• description：（可选）PKI装载说明

create_pki_issuer

创建新的PKI颁发者。

• mount：PKI引擎的装载路径
• name：发行人名称
• certificate：PEM编码证书
• privateKey：PEM编码的私钥

list_pki_issuers

列出装载中的所有PKI颁发者。

• mount：PKI引擎的装载路径

read_pki_issuer

读取特定PKI颁发者的详细信息。

• mount：PKI引擎的装载路径
• name：发行人名称

create_pki_role

创建用于颁发证书的新PKI角色。

• mount：PKI引擎的装载路径
• name：角色名称
• config：角色配置参数（TTL、允许的域等）

read_pki_role

读取PKI角色配置。

• mount：PKI引擎的装载路径
• name：角色名称

list_pki_roles

列出装载中的所有PKI角色。

• mount：PKI引擎的装载路径

list_pki_证书

列出PKI装载颁发的证书序列号。吊销的证书将自动从列表中排除。

• mount：PKI引擎的装载路径

read_pki_metadata

读取特定证书序列的元数据，而不返回完整证书。

• mount：PKI引擎的装载路径
• serial：证书的序列号（匹配 list_pki_certificate 输出）

read_pki_证书_元数据

从Vault读取证书，并从证书本身提取元数据信息（通用名称、主题、颁发者、有效日期、SAN、密钥使用等）。

• mount：PKI引擎的装载路径
• serial：证书的序列号（匹配 list_pki_certificate 输出）

delete_pki_role

删除PKI角色。

• mount：PKI引擎的装载路径
• name：角色名称

issue_pk_证书

使用PKI角色颁发新证书。

• mount：PKI引擎的装载路径
• role：要使用的角色名称
• commonName：证书的通用名称
• altNames：（可选）证书的替代名称
• ipSans：（可选）证书的IP SAN
• ttl：（可选）证书到期时间

命令行用法

# Show help
./vault-mcp-server --help

# Run in stdio mode (default)
./vault-mcp-server
./vault-mcp-server stdio

# Run in HTTP mode
./vault-mcp-server http --transport-port 8080 --transport-host 127.0.0.1

# Show version
./vault-mcp-server --version

# Run with custom log file
./vault-mcp-server --log-file /path/to/logfile.log

使用MCP检查器

您可以使用 这 @模型上下文协议/检查器 该工具用于通过web UI检查正在运行的Vault MCP服务器并与之交互。

对于HTTP模式：

npx @modelcontextprotocol/inspector http://localhost:8080/mcp

对于stdio模式：

npx @modelcontextprotocol/inspector ./vault-mcp-server

发展

建筑

# Build the binary
make build

# Build with Docker
make docker-build

# Clean build artifacts
make clean

测试

# Run tests
make test

# Run end-to-end tests
make test-e2e

# Test HTTP endpoint
make test-http

项目结构

vault-mcp-server/
├── bin/                                  # Binary output directory
│   └── vault-mcp-server                  # Compiled binary
├── cmd/vault-mcp-server/                 # Main application entry point
│   ├── init.go                           # Initialization code
│   └── main.go                           # Main application
├── pkg/                                  # Package directory
│   ├── client/                           # Client implementation
│   │   ├── client.go                     # Core client functionality
│   │   └── middleware.go                 # HTTP middleware
│   ├── tools/                            # MCP tools implementation
│   │   ├── kv/                           # Key-Value tools
│   │   ├── pki/                          # PKI certificate tools
│   │   ├── sys/                          # System management tools
│   │   └── tools.go                      # Tool registration
│   └── utils/                            # Utility functions
├── scripts/                              # Build and utility scripts
├── version/                              # Version information
├── e2e/                                  # End-to-end tests
├── Dockerfile                            # Container build definition
├── Makefile                              # Build automation
├── go.mod                                # Go module definition
└── LICENSE                               # License information

支持

有关错误报告和功能请求，请打开 .

有关一般问题和讨论，请打开GitHub讨论。