STARWARCLOUD STARWAR.AI
返回市场
金库-MCP

金库-MCP

作者：rccyx5 星标更新：2025-11-02
安装使用来源：spider==github.com

项目介绍

HashiCorp Vault MCP 服务器

HashiCorp Vault MCP 服务器是一个全功能的模型上下文协议（MCP）集成，允许语言模型和其他支持MCP的客户端通过一个安全且可审计的接口管理Vault的秘密和策略。它将Vault的安全模型与MCP期望的结构化交互模型连接起来，因此您可以自动化诸如凭证轮换、策略编写和发现等任务，而无需暴露原始的Vault API。

目录

简介

该服务器封装了HashiCorp Vault KV v2 API和常见的策略工作流程，这些都在MCP原语中实现。一旦客户端连接，它可以调用类型化的工具，浏览资源，并请求由您已操作的同一Vault实例支持的提示完成。每次交互都是明确的：客户端必须提供它们想要处理的路径、数据和策略，服务器使用您控制的令牌将这些请求直接转发给Vault。

<img width="1222" height="909" alt="image" src="https://github.com/user-attachments/assets/4517458f-e882-4928-83ba-2ba3be2354a0" />

为什么使用此服务器

  • 直接从兼容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密钥引擎（v2）在您计划管理的路径上启用。
  • 一个以hvs.开头并授予所需能力（读取、创建、更新、删除以及/或sudo用于策略工作）的Vault令牌。
  • Docker 24+。
  • 运行MCP服务器的机器到您的Vault集群的网络访问。

开始使用

Cursor

生产（推荐）——使用官方镜像。将以下内容粘贴到~/.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）。

本地Cursor

您可以构建并运行本地服务，并这样使用：

{
  "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-m-:local

配置

  • VAULT_ADDR（必需）：Vault集群的URL，例如https://vault.internal:8200或http://127.0.0.1:8200。
  • VAULT_TOKEN（必需）：以hvs.开头的短期或可续期Vault令牌。使用Vault策略严格限定其作用域。
  • NODE_TLS_REJECT_UNAUTHORIZED（可选）：仅在使用自签名证书测试时设置为0。建议添加正确的CA捆绑包。

如果部署需要其他Vault环境变量（如VAULT_NAMESPACE），请提供；服务器将进程环境转发给Vault客户端库。

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

工具参考

MCP服务器公开了直接映射到Vault操作的工具。在发送到Vault之前会验证负载，响应则模仿Vault的JSON结构。

create_secret

  • 目的：在KV v2路径写入或更新一个秘密。
  • 输入：
    • path（字符串）：KV v2逻辑路径，例如apps/myapp/config。
    • data（对象）：存储在data下的键值对。
  • 响应：返回包括版本元数据的Vault写入响应。
await tool("create_secret", {
  path: "apps/myapp/config",
  data: {
    apiKey: "secret-key-123",
    environment: "production",
  },
});

read_secret

  • 目的：从KV v2检索特定版本的秘密。
  • 输入：
    • path（字符串）：KV v2逻辑路径。
    • version（可选数字）：要获取的具体版本，默认为最新版本。
  • 响应：Vault的data对象连同元数据（created_time，version）。
const secret = await tool("read_secret", { path: "apps/myapp/config" });
console.log(secret.data.apiKey);

delete_secret

  • 目的：软删除KV v2秘密的最新版本。
  • 输入：
    • path（字符串）：KV v2逻辑路径。
  • 响应：Vault删除元数据。除非单独销毁，否则旧版本仍然存在。
await tool("delete_secret", { path: "apps/myapp/config" });

create_policy

  • 目的：创建或替换Vault ACL策略。
  • 输入：
    • name（字符串）：要插入或更新的策略名称。
    • policy（字符串）：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（字符串）：目标KV路径或模式，例如secret/data/apps/*。
    • capabilities（字符串）：逗号分隔的能力（例如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/...）。
  • 自签名证书错误：通过VAULT_CACERT提供CA捆绑包，或在测试时暂时设置NODE_TLS_REJECT_UNAUTHORIZED=0。
  • 资源看起来为空：令牌只能看到它被允许list的路径。请再次检查策略是否允许相关前缀上的list能力。

许可

根据MIT许可分发。