Vault MCP

HashiCorp保险库MCP服务器

HashiCorp Vault MCP Server是一个功能齐全的模型上下文协议（MCP）集成，允许语言模型和其他支持MCP的客户端通过安全、可审计的界面管理Vault机密和策略。它将Vault的安全模型与MCP期望的结构化交互模型连接起来，因此您可以在不暴露原始Vault API的情况下自动化凭据轮换、策略编写和发现等任务。

目录

• HashiCorp保险库MCP服务器

- 目录 - 引言 - 为什么使用此服务器 - 服务器的工作原理 - 需求 - 入门指南 - 光标 - 本地游标 - - 配置 - 工具参考 - create_secret - read_secret - delete_secret - create_policy - 资源引用 - vault://secrets - vault://policies - 快速参考 - generate_policy - 故障排除 - 许可证

引言

服务器将HashiCorp Vault KV v2 API和通用策略工作流封装在MCP基元中。一旦客户端连接，它就可以调用类型化工具、浏览资源并请求提示完成，所有这些都由您已经操作的同一Vault实例支持。每次交互都是明确的：客户端必须提供他们想要使用的路径、数据和策略，服务器使用您控制的令牌将这些请求直接中继到Vault。

为什么使用此服务器

• 直接从MCP兼容的IDE和代理中自动进行秘密轮换和检索。
• 生成或更新Vault ACL策略，而无需手动编辑HCL代码段。
• 通过限定为服务器供电的Vault令牌的范围，仅安全地公开您批准的操作。
• 避免临时脚本编写：服务器附带了围绕常见Vault任务设计的定义良好的工具和提示。

服务器的工作原理

1. 您可以在本地或带有Vault令牌的容器内启动服务器。
2. MCP客户端（Cursor、Claude Desktop、自定义代理）通过stdio连接。
3. 客户调用以下工具 create_secret 或 create_policy；服务器验证有效负载，将其转发到Vault，并返回结构化响应。
4. 资源请求，例如 vault://secrets 列出客户端可以浏览或提供给后续提示的数据驱动内容。
5. 提示处理程序，如 generate_policy 帮助您从自然语言意图合成Vault就绪的HCL。

该实现是用TypeScript编写的，捆绑在一个JavaScript文件中，并依赖于官方 @modelcontextprotocol/sdk 用于传输和模式验证。

需求

• HashiCorp Vault 1.9+在您计划管理的路径上启用了KV secrets引擎（v2）。
• 以开头的Vault令牌 hvs. 并授予您所需的功能（读取、创建、更新、删除和/或使用sudo进行策略工作）。
• Docker 24+。
• 从运行MCP服务器的计算机到Vault群集的网络访问。

入门指南

光标

生产（推荐）——使用官方形象。将此粘贴到下面 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "Vault": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "VAULT_ADDR=https://your-vault-server:8200",
        "-e",
        "VAULT_TOKEN=hvs.your-vault-token",
        "ashgw/vault-mcp:latest"
      ]
    }
  }
}

Cursor按需启动容器，将stdio连接到MCP传输，并在会话结束后将其拆除。固定标签（例如。 ashgw/vault-mcp:1.x.y)如果你想要一个固定版本。

本地游标

您可以在本地构建和运行，并像这样使用它

{
  "mcpServers": {
    "Vault": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network=host",
        "-e",
        "VAULT_ADDR=http://127.0.0.1:8200",
        "-e",
        "VAULT_TOKEN=hvs.test-token-1234567890abcdef",
        "vault-mcp:local"
      ]
    }
  }
}

本地Docker

git clone https://github.com/rccyx/vault-mcp.git
cd vault-mcp
docker build -t vault-mcp:local .

docker run -i --rm \
  --network=host \
  -e VAULT_ADDR=http://127.0.0.1:8200 \
  -e VAULT_TOKEN=hvs.test-token-1234567890abcdef \
  vault-mcp:local

配置

• VAULT_ADDR （必填）：例如Vault集群的URL https://vault.internal:8200 或 http://127.0.0.1:8200.
• VAULT_TOKEN （必填）：以以下字符开头的短期或可再生Vault令牌 hvs.。使用Vault策略严格限定范围。
• NODE_TLS_REJECT_UNAUTHORIZED （可选）：设置为 0 仅用于使用自签名证书进行测试。更倾向于添加适当的CA包。

提供任何其他Vault环境变量（例如 VAULT_NAMESPACE)如果您的部署需要它们；服务器将流程环境转发到Vault客户端库。

对于本地的正常测试默认值，请使用 .env.copy.example 文件。

工具参考

MCP服务器公开了直接映射到Vault操作的工具。有效载荷在发送到Vault之前经过验证，响应反映了Vault的JSON结构。

create_secret

• 目的：在KV v2路径上写入或更新机密。
• 输入:

- path （string）：例如KV v2逻辑路径 apps/myapp/config. - data （object）：要存储的键/值对 data.

• 响应：返回包含版本元数据的Vault写入响应。

await tool("create_secret", {
  path: "apps/myapp/config",
  data: {
    apiKey: "secret-key-123",
    environment: "production",
  },
});

read_secret

• 目的：从KV v2检索特定的秘密版本。
• 输入:

- path （string）：KV v2逻辑路径。 - version （可选数字）：要获取的显式版本；默认为最新。

• 响应：保险库 data 对象和元数据(created_time, version).

const secret = await tool("read_secret", { path: "apps/myapp/config" });
console.log(secret.data.apiKey);

delete_secret

• 目的：软删除KV v2密钥的最新版本。
• 输入:

- path （string）：KV v2逻辑路径。

• 响应：Vault删除元数据。除非单独销毁，否则旧版本将保留。

await tool("delete_secret", { path: "apps/myapp/config" });

create_policy

• 目的：创建或替换Vault ACL策略。
• 输入:

- name （string）：要追加销售的策略名称。 - policy （string）：HCL策略定义。

• 响应: true 关于成功。

await tool("create_policy", {
  name: "app-readonly",
  policy: """
path "secret/data/apps/myapp/*" {
  capabilities = ["read", "list"]
}
"""
});

资源引用

资源公开了可浏览的数据集，帮助MCP客户端决定下一步进行哪个工具调用。

vault://secrets

列出KV存储根目录下可用的密钥。嵌套目录以结尾 / 这样客户就可以钻得更深。

{
  "keys": ["apps/", "databases/", "certificates/"]
}

vault://policies

枚举令牌可以读取的策略名称。可用于审核或输入提示。

{
  "policies": ["default", "app-readonly", "admin"]
}

快速参考

提示通过将结构化输入转换为Vault友好的输出来帮助完成更高级别的创作任务。

generate_policy

• 输入:

- path （string）：目标KV路径或模式，如 secret/data/apps/*. - capabilities （string）：逗号分隔的功能（例如 read,list,delete).

• 响应：JSON对象，将路径映射到功能数组，以便您可以将结果嵌入ACL策略或将其反馈到 create_policy.

const draft = await prompt("generate_policy", {
  path: "secret/data/apps/*",
  capabilities: "read,list",
});

故障排除

• 认证失败：确认 VAULT_TOKEN 有效且未被撤销。跑 vault token lookup hvs.your-token 检查TTL和策略。
• 路径的权限被拒绝：调整附加到令牌的Vault策略，或验证您的目标是正确的装载（例如 secret/data/... 对 kv/data/...).
• 自签名证书错误：通过以下方式提供CA捆绑包 VAULT_CACERT 或临时设置 NODE_TLS_REJECT_UNAUTHORIZED=0 在测试过程中。
• 资源看起来是空的：令牌只看到它被允许的路径 list.仔细检查政策是否允许 list 相关前缀的能力。

许可证

分布在 MIT许可证.