Wundervault MCP

@wundervault/mcp-server

面向 AI Agent 的零知识机密库。 你粘贴到 Agent 聊天或 .env 文件中的每个 API 密钥，最终都会进入上下文窗口、对话记录和提供商日志。Wundervault 的解决方案是：Agent 根本不会收到机密。它只需请求执行工作——“注入密钥并运行此部署”——本地守护进程便会解密机密，将其注入子进程环境，清零缓冲区，并在 Agent 看到任何输出之前清理输出。

此仓库是 MCP 服务，可将该工作流提供给任何 Model Context Protocol 客户端使用，包括 Claude Code、Cursor、Cline 等。

不要轻信这项声明——亲自验证： 你可以在自己的网络边界独立验证零知识属性，整个过程约需 5 分钟（使用浏览器开发者工具或 mitmproxy 金丝雀测试）。指南和我们的测试记录：wundervault.com/verify。

工作原理

┌──────────────┐  MCP (stdio)  ┌───────────────────┐  ciphertext only  ┌───────────────────┐
│   AI agent   │──────────────▶│  wundervault-mcp  │◀─────────────────▶│  wundervault.com  │
│ (Claude, …)  │◀──────────────│  + local daemon   │                   │ stores encrypted  │
└──────────────┘ "burned" ack  │  decrypts HERE    │                   │ blobs, no keys    │
                               └─────────┬─────────┘                   └───────────────────┘
                                         │  secret → subprocess env
                                         │  (buffer zeroed after spawn)
                                         ▼
                               ┌───────────────────┐
                               │   your command    │ stdout/stderr scrubbed
                               │ (deploy, API, …)  │ before the agent sees it
                               └───────────────────┘

机密会在上传前于客户端加密（通过 Web Crypto 使用 AES-256-GCM）。托管服务只存储密文，无法推导出密钥、口令或明文。

安装

npm install -g @wundervault/mcp-server

快速开始

{
  "mcpServers": {
    "wundervault": {
      "command": "wundervault-mcp",
      "env": {
        "WUNDERVAULT_AGENT_NAME": "<agent-name>"
      }
    }
  }
}

密钥绝不会写入 MCP 配置。服务会为自己命名 Agent，然后通过 Unix 套接字向本地 wundervault-agent 守护进程请求该 Agent 的凭据。 onboard.py 会注册 Agent 并启动守护进程。

新账户？wundervault.com 提供 90 秒的 Agent 上手流程，可为你生成此配置。

支持的平台

Linux 是经过验证的平台。 macOS 可用于交付机密；Windows 不支持。

从设计上看，交付仅支持 POSIX：sudo 配方通过管道调用 /bin/sh，而 git / ssh-passphrase 配方需要 mkfifo 和 setsid。在 Windows 上，这些 机制会返回明确的“不支持”错误，而不会在深层执行过程中才失败。

单实例锁有两种实现：Linux 上使用由内核持有的抽象套接字，其他平台则使用回环端口。只有 Linux 版本经过测试——有关 macOS 上未经验证的内容及其原因，请参阅 HANDOFF-lock-on-non-linux.md。CI 会在两个平台上运行；锁测试套件则在 Linux 上运行。

安全模型

• 零知识： 加密密钥仅存在于 MCP 服务进程中。Wundervault 服务永远无法看到密钥。
• 阅后即焚： 绝不会向调用它的 Agent 返回明文机密。解密后，Agent 只会收到 "Secret retrieved and burned."。
• 执行清理： 返回命令的标准输出/标准错误前，会先清理其中的明文；shell 转义模式（$()、反引号、sh -c、eval）以及重定向机密到文件的操作会在解密前被拒绝。
• 指令完整性： 在释放任何机密前，会验证服务端指令签名（PBKDF2-HMAC-SHA256，600k 次迭代）。
• 时序安全： HMAC 比较使用 crypto.timingSafeEqual。
• 分级访问： 服务端会强制执行每条记录的访问级别；Agent 使用高级别机密前需要获得人工批准。

明确的局限

• 该平台采用开放核心模式：此 MCP 服务和 browser crypto 采用 AGPL-3.0 许可，因此你可以审查所有接触机密信息的部分，但托管服务本身并非开源。
• 必须在 Agent 旁边运行本地守护进程；完全隔离网络的环境不适用。
• 按设计，Agent 永远无法读取机密信息的值——如果你的工作流需要模型对机密信息本身进行推理，这种方案并不适合。

工具

vault_entries_list

列出此 Agent 可用的所有保险库条目。返回条目 ID 和机密名称，不包含值。

Input: {}
Output: "Vault entries (N):\n  [entry_id]  secret_name  (tier: read)"

vault_entry_get

检索并解密保险库机密信息。也可以使用该信息执行命令。

Input:
  entry_id: string          # from vault_entries_list
  purpose: string           # audit log reason
  exec?: string             # optional shell command

Output: "Secret retrieved and burned." (plaintext NEVER returned)

安全执行模式（sudo 示例）：

sudo -S systemctl restart nginx <<< "$WUNDERVault_SECRET"

请勿使用 echo $WUNDERVault_SECRET | sudo -S——这会导致机密信息暴露在进程日志中。

vault_exec

使用注入环境变量的保险库机密信息执行 shell 命令，可在本地执行，也可通过 SSH 在远程主机上执行。机密信息会注入子进程，并在启动后立即将缓冲区清零；解密前会拒绝转义模式。

Input:
  purpose: string           # audit log reason
  command: string           # full shell command (no escape patterns)
  entry_id?: string         # secret to inject (omit for SSH-key-only remote exec)
  working_dir?: string
  inject_as?: { env_key, pre_command?, post_command? }   # override entry's exec_config
  remote_host?: { host, user, ssh_key_entry_id? | ssh_key? }

使用 remote_host.ssh_key_entry_id 时，会从保险库获取 SSH 密钥并使用，过程中绝不会将其写入磁盘。

vault_entry_inject_env

将保险库机密信息直接写入配置文件（~/.npmrc、~/.netrc、~/.docker/config.json 或项目的 .env），明文不会经过 Agent。

Input:
  entry_id: string
  purpose: string
  file_path: string         # allowed config file paths only
  env_key: string           # variable name to set

vault_rsync

通过 SSH 使用 rsync 将本地目录同步到远程主机，SSH 密钥从保险库获取（传输完成后立即删除临时密钥文件）。

vault_entry_forget

丢弃本地引用。在服务器上不执行任何操作。

Input: { entry_id: string }
Output: "Reference [id] discarded from local context."

凭据

MCP 服务不持有自己的密钥，也不会通过命令行接收密钥。首次调用工具时，它会按以下方式获取凭据：

1. WUNDERVAULT_AGENT_NAME（必填）用于指定此进程对应的已注册 Agent。
2. Agent 令牌从 WUNDERVAULT_AGENT_TOKEN 读取，或从 ~/.wundervault/agents/<name>.token 读取。
3. 该令牌会通过 ~/.wundervault/agents/<name>.sock 发送给本地守护进程，由其返回 API 密钥、加密密钥和保险库 URL。

如果守护进程未运行，工具调用会失败并给出相关说明，不会回退到安全性较低的信息源。运行 onboard.py 以注册 Agent 并启动守护进程。

CLI 选项

wundervault-mcp [options]

  --url <url>   API base URL override (default: supplied by the daemon)
  --help        Show help

没有 --api-key、--enc-key 或 --credentials 选项。未知选项会被拒绝。

Agent 钱包（x402）

x402 支付本质上只是一个签名，钱包密钥也和其他保险库机密信息一样。将密钥存储在第 2 层，让 Agent 通过 vault_exec 对支付载荷签名，密钥会注入本地签名子进程——绝不会进入模型上下文，并且每次使用前都需要所有者批准（Agent 被拒绝的调用会携带请求 ID；批准范围限定为该 Agent 和该机密信息，可批准一次，也可在 15/60 分钟时段内批准）。我们已在 Base Sepolia 上完成端到端测试——经验证的测试记录已发布在 wundervault.com/agent-wallets。 针对支付的策略（消费上限、收款方允许列表）尚未实现：目前兼容，但还没有产品化。

沙盒 / 演示模式

设置 WUNDERVAULT_MOCK=1，即可在不运行 wundervault-agent 守护进程、也不提供任何凭据的情况下运行服务。在此模式下，每次工具调用都会返回明确标记为 [DEMO MODE] 的示例响应，而不是联系保险库——不会涉及任何真实机密信息。此模式方便你在没有账户的情况下试用工具接口，也方便 MCP 目录扫描器和 CI （例如 Glama）启动服务、调用每个工具并在没有连接真实保险库的情况下验证构建。此模式默认关闭，生产环境中绝不会启用。

"env": { "WUNDERVAULT_MOCK": "1" }   // demo/CI only — returns fake, labelled output

从源代码构建

git clone https://github.com/wundervault/wundervault-mcp.git
cd wundervault-mcp
npm install
npm run build   # compiles TypeScript to dist/
npm test        # run the test suite

获取最新动态

版本发布、安全公告和产品文章会发布在 X 上，账号为 @wundervault1。完整的版本发布历史：wundervault.com/changelog。

许可证

本项目采用 GNU Affero 通用公共许可证 v3.0 或更高版本（AGPL-3.0-or-later）授权。请参阅 LICENSE。

Wundervault 采用开放核心模式：此 MCP 服务和客户端均为开源；wundervault.com 上的托管服务则为商业产品。如有商业合作或托管服务方面的咨询，请通过 wundervault.com/contact 联系我们。