使用说明

MCP保险库

AI协助HashiCorp保管库管理，向AI提供商发送零秘密

🔐 你的秘密永远不会离开你的基础设施 -任何兼容MCP的AI（Claude、Gemini、Qwen、OpenAI）都可以通过本地MCP服务器帮助您管理Vault，该服务器将所有敏感数据保存在您的机器上。人工智能看到的是结构和工作流程，而不是真正的秘密。

🤖 适用于任何MCP客户端： Claude Code、Gemini CLI、OpenAI代理、Qwen代理、BoltAI、Chatbox和 469+MCP客户端

MCP Vault提供两个互补工具：

🤖 MCP服务器 -用于AI辅助的模型上下文协议集成（适用于任何MCP客户端）
💻 命令行界面 -用于基于会话的Vault身份验证和秘密管理的Bash脚本

为什么存在

个人背景： 这个项目诞生于管理一个拥有20多个服务的Proxmox家庭实验室，每个服务都有分散的凭据，需要适当的集中秘密管理和清理基础设施混乱的方法。

问题： 管理许多Docker/Docker组合服务，每个服务都有自己的 .env 文件和硬编码凭证散落各处。不可扩展，不安全，不适合生产。

目标： 从非生产混乱中迁移（docker中的密码组成文件，未被跟踪 .env 文件）转换为满足以下要求的面向生产的HashiCorp Vault设置：

云兼容 -必须跨基础设施工作
人工智能辅助 -需要您的AI代理帮助迁移服务和管理机密
缺省安全 -要求通过WebAuthn进行人工在环验证，以防止未经授权的AI写入

结果： 人工智能处理繁琐的迁移工作（读取旧配置、注册机密），但 不能进行未经授权的更改 未经您的生物识别批准，不得泄露生产机密。

注：整个项目都是用Claude Code构建的——通过对话设计，将人类意图与人工智能实现相结合。

🌟 主要特点

运作原理

┌─────────────────┐
│   You ask AI    │  "Scan my .env files and migrate to Vault"
│  (MCP Client)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   MCP Server    │  → Tokenizes secrets: PASSWORD="super_secret"
│  (Your Machine) │     becomes PASSWORD="@token-abc123"
└────────┬────────┘  → AI never sees real values
         │
         ├──────────────────────────────────────┐
         │                                      │
         ▼                                      ▼
┌─────────────────┐                   ┌─────────────────┐
│  AI Provider    │                   │  Approval Page  │
│    (Remote)     │                   │  (Your Browser) │
└─────────────────┘                   └────────┬────────┘
Sees: @token-abc123                            │
Never sees: super_secret              Approve with TouchID
                                               │
         ┌─────────────────────────────────────┘
         ▼
┌─────────────────┐
│ HashiCorp Vault │  ✓ Secrets stored securely
│  (Your Infra)   │  ✓ Changes approved by you
└─────────────────┘  ✓ Full audit trail

核心能力

🔒 零知识人工智能 -秘密在到达人工智能提供商之前被标记；MCP服务器在本地运行，真正的价值永远不会离开您的基础设施

🤖 人工智能辅助迁移 -用于扫描的自然语言命令 .env 文件、docker编写配置，并自动将机密迁移到Vault

🛡️ 人在环安全 -所有写入操作都需要WebAuthn生物识别批准（TouchID/Windows Hello/YubiKey）

💻 生产准备就绪 -OIDC+MFA认证、全面的审计跟踪、操作历史跟踪（100次操作，永久保留）

WebAuthn审批工作流

1. Home Dashboard

Monitor server status, view pending approvals, and manage registered WebAuthn devices.

2. Review Operation

Examine the service name, operation type, and preview secret values before approving.

3. Biometric Authentication

Confirm with TouchID, Windows Hello, or hardware security key for cryptographic verification.

4. Approval Complete

Success confirmation with audit trail. The operation is now processed and logged.

🎯 用例

主要：将Docker服务迁移到Vault

问题： 你有20多个docker组合服务，密码硬编码，分散 .env 文件夹。

完成工作流程：

你： “扫描/services/jellyfin中的docker-compose.yml，并将机密迁移到Vault”
人工智能： 呼叫 vault_scan_compose(service="jellyfin")
- MCP服务器读取您的docker-compose.yml
- 检测机密（密码、API密钥等）
- 将它们标记化: JELLYFIN_PASSWORD="@token-a8f3d9e1"
- 创建需要WebAuthn批准的操作

人工智能： 向您显示：

📋 Found 5 secrets in jellyfin/docker-compose.yml:
- JELLYFIN_PASSWORD: @token-a8f3d9e1
- API_KEY: @token-b2c4f7a9
- DB_PASSWORD: @token-c5d6e8f9

⚠️  Approve at: http://localhost:8091/approve/xyz123

你：在浏览器中打开审批URL
- 查看真实价值 审批页面中的（非令牌）
- 审核：服务名称、操作类型、所有机密
- 点击“使用WebAuthn批准”
- 使用TouchID/Windows Hello进行身份验证
人工智能： 批准后，致电 vault_set()
- 在Vault中注册机密 secret/proxmox-services/jellyfin
- 生成 .env.example 随着 <REDACTED> 占位符
- 创建文档

结果： 机密已迁移到Vault，记录了旧的.env文件，但可以删除

其他常见任务

审核和轮换机密

需要使用特定的数据库密码查找所有服务吗？自然地问你的AI：

"Which services are using the old database password?"
"Help me rotate the database credentials for all affected services"

AI通过MCP服务器读取Vault，以帮助您了解您的秘密环境，但任何更改都需要您的生物识别批准。

生成服务配置

设置需要Vault中10多个环境变量的新服务？让你的AI来处理它：

"Create a .env file for my new API service using secrets from Vault"

MCP服务器在本地注入真实值——AI永远看不到它们，只是编排工作流程。

基础设施即代码

在不暴露秘密的情况下对服务结构进行版本控制：

提交 .env.example 文件与 <REDACTED> 将占位符转换为git
将实际秘密保存在Vault中
AI帮助您从现有设置中生成示例文件

📦 安装

先决条件

HashiCorp保险库 已配置OIDC身份验证的服务器
Python 3.12+ （适用于MCP服务器）
MCP兼容AI客户端 （Claude Code、Gemini CLI、OpenAI代理等）
支持WebAuthn的现代浏览器（Chrome、Firefox、Safari、Edge）

安装选项

选项A:PyPI的MCP服务器（推荐-不需要回购克隆！）

# Install directly from PyPI
pip install mcp-vault

# Or using uvx (recommended - auto-managed environment)
uvx --from mcp-vault vault-approve-server --help

添加到您的MCP客户端 -在中配置 .mcp.json:

{
  "mcpServers": {
    "mcp-vault": {
      "command": "uvx",
      "args": ["mcp-vault"],
      "env": {
        "VAULT_ADDR": "https://vault.example.com",
        "VAULT_TOKEN": "${VAULT_TOKEN}",
        "VAULT_SECURITY_MODE": "tokenized"
      }
    }
  }
}

兼容：

克劳德代码/克劳德桌面
Gemini CLI(gemini-cli --mcp-server mcp-vault)
OpenAI代理SDK
BoltAI、Chatbox和所有MCP客户端

在MCP目录中查找此服务器：

Smithery.ai -官方Anthropic维护目录
出色的MCP服务器 -精心策划的社区名单（高知名度）
mcp.so -拥有17K+服务器的社区平台

选项B：仅限CLI（用于直接Vault管理）

# Quick install from release
curl -fsSL https://github.com/weber8thomas/mcp-vault/releases/latest/download/install.sh | sudo bash

# Or install to ~/.local/bin (no sudo)
curl -fsSL https://github.com/weber8thomas/mcp-vault/releases/latest/download/install.sh | PREFIX="$HOME/.local/bin" bash

# Verify installation
vault-session --help

选项C：开发安装（来源）

# Clone repository
git clone https://github.com/weber8thomas/mcp-vault.git
cd mcp-vault

# Install MCP server in editable mode
cd packages/mcp-server
pip install -e .

# Install CLI tools (optional)
cd ../..
sudo ./install.sh

# Verify installations
vault-approve-server --help
vault-session --help

存储库结构

mcp-vault/
├── packages/
│   ├── mcp-server/       # Python MCP server for any MCP client (recommended)
│   └── cli/              # Bash CLI scripts for Vault operations
└── docs/                 # Documentation

🚀 快速开始

完整的MCP服务器工作流程（人工智能辅助管理）

假设您已经安装了MCP服务器（请参阅上面的安装部分）

步骤1：审批服务器

审批服务器 自动启动 当MCP服务器首次使用时。它运行于 http://localhost:8091 您将在哪里：

注册您的WebAuthn设备（TouchID/Windows Hello/YubiKey）
审查和批准人工智能请求的操作
查看操作历史记录和待审批

注： MCP服务器会自动启动审批服务器。您还可以手动启动它 vault-approve-server 如果需要测试。

步骤2：通过Vault身份验证

在另一个终端中，验证您的会话：

source vault-session login

这将：

在浏览器中打开您的Vault OIDC登录页面
身份验证提示（例如Authentik、Okta等）
集 VAULT_TOKEN 和 VAULT_TOKEN_EXPIRY 在您的环境中
会话持续60分钟（可配置）

验证身份验证：

vault-session status

步骤3：配置MCP客户端

添加到您的MCP客户端配置中（例如。， .mcp.json 克劳德代码）：

{
  "mcpServers": {
    "mcp-vault": {
      "command": "uvx",
      "args": ["mcp-vault"],
      "env": {
        "VAULT_ADDR": "https://vault.example.com",
        "VAULT_TOKEN": "${VAULT_TOKEN}",
        "VAULT_SECURITY_MODE": "tokenized"
      }
    }
  }
}

重要提示： MCP服务器继承 VAULT_TOKEN 从您的shell环境中。

请参阅详细的配置指南：

MCP客户端配置 -所有MCP客户端（Claude Desktop、Gemini CLI等）
生产部署 -Nginx/HTTPS设置
环境变量 -所有配置选项

步骤4：注册WebAuthn设备

打开http://localhost:8091在浏览器中
点击 “注册身份验证器”
按照提示注册您的生物识别设备
您已准备好使用您的AI助手，并获得安全批准！

步骤5：与您的AI助手一起使用

现在让你的人工智能帮助管理你的秘密：

"Scan my docker-compose.yml for secrets and help me migrate them to Vault"

当AI需要写秘密时，它会：

向您展示标记化的预览（秘密替换为 @token-xxx)
提供批准URL：http://localhost:8091/approve/｛操作id｝
等待您的WebAuthn批准
批准后处理操作

CLI工作流（手动Vault管理）

假设您已经安装了CLI（请参阅上面的安装部分）

步骤1：通过Vault身份验证

source vault-session login

这将：

在浏览器中打开您的Vault OIDC登录
提示MFA（例如Authentik）
集 VAULT_TOKEN 在您的环境中
会话持续60分钟

步骤2：验证会话

vault-session status

预期产量：

✅ Vault Session Active
User: your-username
Policies: default, homelab-services
Time Remaining: 59m 30s

步骤3：使用CLI命令

列出所有服务：

vault-session list

获取服务的秘密：

vault-session get jellyfin
# Returns: API_KEY, DB_PASSWORD, etc.

注册新机密：

vault-session set myapp API_KEY=abc123 DB_PASS=secret

将机密注入.env文件：

vault-session inject myapp
# Creates myapp/.env with real values from Vault

注销（撤销令牌）：

vault-session logout

可用命令

命令	描述	示例
`login`	通过OIDC+MFA进行身份验证	`source vault-session login`
`status`	检查会话有效性	`vault-session status`
`logout`	撤销保险库令牌	`vault-session logout`
`list`	列出服务/秘密	`vault-session list` 或 `vault-session list myapp`
`get`	获取机密值	`vault-session get myapp`
`set`	创建/更新机密	`vault-session set myapp KEY=value`
`inject`	将机密写入.env	`vault-session inject myapp`

🔐 安全

MCP保险库使用 纵深防御 安全：

图层	保护	工作原理
分词	秘密从未发送到AI API	真实值被替换为 `@token-xxx` 占位符
WebAuthn批准	人在循环中写入	需要TouchID/Windows Hello来批准操作
保险库集成	企业秘密存储	静态和传输中的行业标准加密
会话管理	限时访问	OIDC令牌在60分钟后过期

快速安全模型

┌──────────────────┐
│  AI Provider     │  ← Sees: Tokens only (e.g., @token-a8f3d9e1)
│ (Claude/Gemini)  │     Never sees: Actual secret values
└────────┬─────────┘
         │ MCP Protocol
┌────────▼─────────┐
│   MCP Server     │  ← Full access to secrets
│ (Your Machine)   │     WebAuthn approval enforced for writes
└────────┬─────────┘
         │ Vault API
┌────────▼─────────┐
│  HashiCorp Vault │  ← Encrypted secret storage
│ (Your Infra)     │     OIDC/MFA controlled access
└──────────────────┘

阅读完整的安全架构： docs/SECURITY.md

文档

MCP服务器

MCP集成 -模型上下文协议服务器设置
WebAuthn安装程序 -安全架构和常见问题
MCP服务器自述文件 -MCP包详细信息

CLI工具

安装指南 -完成安装和配置
快速开始 -CLI参考指南
CLI自述文件 -CLI包详细信息

发布

推送新版本标签时，会自动创建版本。每个版本包括：

install.sh -独立安装程序（从GitHub下载最新版本）
vault-session-vX.X.X-linux-amd64.tar.gz -完整的tarball档案
vault-session-vX.X.X-linux-amd64.zip -完整ZIP存档
checksums.txt -SHA256校验和用于验证

从版本开始安装一个命令：

curl -fsSL https://github.com/weber8thomas/claude-vault/releases/latest/download/install.sh | sudo bash

要创建新版本，请执行以下操作：

git tag -a v1.1.0 -m "Release version 1.1.0"
git push origin v1.1.0

GitHub Actions将自动构建并发布该版本。