AI导哈

Vault密钥管理服务器

一个基于Model Context Protocol (MCP)的服务，提供通过Streamable HTTP API与HashiCorp Vault交互的工具，用于密钥的读取、创建、列出和删除操作。

  • by rod-anami
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 rod-anami-kyndryl/hashi-vault-mcp

使用说明

HashiCorp保险库MCP服务器

一种模型上下文协议（MCP）服务器，提供通过可流式HTTP API与HashiCorp Vault交互的工具。

特性

此MCP服务器为Vault KV操作提供以下工具：

  • vault_kv_read：使用可选版本和装载点在指定路径上从Vault读取机密
  • vault_kv_create：在指定路径上创建/向Vault写入机密
  • vault_kv_list：列出装载点中指定路径处的机密
  • vault_kv_delete：从指定路径的Vault中删除最新版本的机密

安全功能

  • 可选承载令牌身份验证：使用基于令牌的身份验证保护您的MCP端点
  • TLS/HTTPS支持：使用自定义证书启用加密连接
  • CORS配置：控制对服务器的跨源访问

安装

npm install
npm run build

先决条件

此服务器使用 hashi-vault-js 图书馆与HashiCorp Vault通信。确保你有：

  • Node.js 18或更高版本
  • 正在运行的HashiCorp Vault服务器
  • 有效的Vault身份验证令牌

配置

服务器支持以下环境变量：

保险库配置（必需）

  • VAULT_ADDR：Vault服务器的地址（默认值： http://127.0.0.1:8200)
  • VAULT_TOKEN：您的Vault身份验证令牌
  • VAULT_URL：完整Vault API URL（默认值： ${VAULT_ADDR}/v1)
  • VAULT_TIMEOUT：请求超时（毫秒）（默认值： 5000)
  • VAULT_CACERT：用于Vault TLS验证的CA证书路径（可选）

MCP服务器配置

  • MCP_PORT：MCP服务器API的端口（默认值： 3000)

安全配置（可选）

  • MCP_AUTH_TOKEN：API身份验证的承载令牌（如果未设置，则禁用身份验证）
  • MCP_TLS_ENABLED：设置为 "true" 启用HTTPS（默认值： false)
  • MCP_TLS_KEY：TLS私钥的路径（默认值： ./certs/mcp-server.key)
  • MCP_TLS_CERT：TLS证书的路径（默认值： ./certs/mcp-server.crt)
  • MCP_TLS_CA：CA证书的路径（默认值： ./certs/ca.crt)

看 .env.example 获取完整的配置模板。

用法

运行服务器

基本（HTTP，无身份验证）：

npm start

使用身份验证：

export MCP_AUTH_TOKEN="your-secure-token-here"
npm start

使用HTTPS：

export MCP_TLS_ENABLED="true"
export MCP_TLS_KEY="./certs/mcp-server.key"
export MCP_TLS_CERT="./certs/mcp-server.crt"
npm start

服务器将公开以下端点：

  • /health -健康检查端点（未受保护）
  • /mcp -客户端连接的MCP端点（如果 MCP_AUTH_TOKEN 已设置）

认证

当 MCP_AUTH_TOKEN 已设置，所有请求 /mcp 必须包括：

Authorization: Bearer <your-token>

有关详细的身份验证设置，请参阅 认证.md.

与Gemini CLI一起使用

将此配置添加到Gemini配置文件中：

MacOS: ~/.config/gemini-cli/config.json

无身份验证：

{
  "mcpServers": {
    "vault": {
      "url": "http://localhost:3000/mcp",
      "transport": "http",
      "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

使用身份验证：

{
  "mcpServers": {
    "vault": {
      "url": "http://localhost:3000/mcp",
      "transport": "http",
      "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
        "Authorization": "Bearer your-secure-token-here"
      }
    }
  }
}

使用HTTPS：

{
  "mcpServers": {
    "vault": {
      "url": "https://localhost:3000/mcp",
      "transport": "http",
      "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
        "Authorization": "Bearer your-secure-token-here"
      }
    }
  }
}

有关更多详细信息，请参阅 双子座_CLI_SETUP.md.

注意：在连接Gemini CLI之前，请确保服务器正在运行。

与Claude Desktop一起使用

将此配置添加到Claude Desktop：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vault": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-token-here"
      }
    }
  }
}

有关更多详细信息，请参阅 COPILOT_SETUP.md.

与其他MCP客户端一起使用

连接到端点 http://localhost:3000/mcp （或 https:// 如果启用了TLS），则使用任何MCP兼容客户端。服务器支持使用StreamableHTTPServerTransport的GET和POST请求。

工具示例

阅读秘密

{
  "tool": "vault_kv_read",
  "arguments": {
    "path": "myapp/config",
    "mount": "secret",
    "version": 1
  }
}

创造/书写秘密

{
  "tool": "vault_kv_create",
  "arguments": {
    "path": "myapp/config",
    "mount": "secret",
    "data": {
      "username": "admin",
      "password": "secret123",
      "api_key": "abc-xyz-123"
    }
  }
}

列出秘密

{
  "tool": "vault_kv_list",
  "arguments": {
    "mount": "secret",
    "folder": "myapp"
  }
}

删除密码

{
  "tool": "vault_kv_delete",
  "arguments": {
    "path": "secret/data/myapp/config"
  }
}

使用cURL进行测试

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your-token" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

有关更多示例，请参见 测试.md.

发展

构建

npm run build

观看模式

npm run watch

保险库设置

为了进行测试，您可以在开发模式下运行Vault：

vault server -dev

这将在以下时间启动Vault http://127.0.0.1:8200 输出中显示根令牌。

安全说明

保险库安全

  • 永远不要承诺你的 VAULT_TOKEN 到版本控制
  • 使用适当的Vault策略限制访问
  • 考虑使用AppRole或其他身份验证方法进行生产
  • 确保您的Vault服务器在生产环境中使用TLS
  • 使用 VAULT_CACERT 验证Vault的TLS证书

MCP服务器安全

  • 启用身份验证：设置 MCP_AUTH_TOKEN 保护您的MCP端点
  • 使用HTTPS：启用 MCP_TLS_ENABLED 用于生产中的加密连接
  • 生成强代币：使用 openssl rand -hex 32 用于身份验证令牌
  • 旋转令牌：定期更改身份验证令牌
  • 网络接入：使用防火墙或反向代理来限制访问
  • 环境安全：从不承诺 .env 带有真实令牌的文件
  • 证书管理：确保TLS证书和密钥的安全(chmod 600)

有关详细的安全指南，请参阅 认证.md.

快速开始

  1. 克隆并安装：

    git clone <repository-url>
cd hashi-vault-mcp
npm install

  2. 配置环境：

    cp .env.example .env
# Edit .env with your Vault details

  3. 构建并运行：

    npm run build
npm start

  4. 测试服务器：

    curl http://localhost:3000/health

其他文件

故障排除

连接问题

  • 验证Vault是否正在运行： vault status
  • 检查 VAULT_ADDR 匹配您的Vault服务器地址
  • 确保 VAULT_TOKEN 具有适当的权限
  • 对于HTTPS Vault，设置 VAULT_CACERT 到您的CA证书路径

身份验证错误

  • 验证 MCP_AUTH_TOKEN 服务器和客户端之间的匹配
  • 检查授权标头格式： Bearer <token>
  • 确保在客户端配置中设置了令牌

TLS/HTTPS问题

  • 验证配置的路径中是否存在证书文件
  • 检查证书文件权限
  • 对于自签名证书，客户端可能需要信任CA或使用 -k 旗帜

许可证

麻省理工学院

相关 MCP