vaultgate

vaultgate

一个可自托管的远程 MCP 服务，让 Claude、Claude Cowork、Claude Code 和 Codex 等托管式 AI Agent 使用你的凭据，却永远无法看到它们。凭据保存在你的 Bitwarden（或 Vaultwarden）保险库中。vaultgate 会代表 Agent，根据你定义的策略，在你指定的系统中使用这些凭据（HTTP API、Microsoft Graph、SQL Server 或 PostgreSQL 数据库、SSH 或 WinRM 主机，或通过 Semble 搜索的 GitHub 仓库），并仅返回结果。它本身就是一个 OAuth 2.1 授权服务，因此 Agent 持有的是短时有效、限定作用范围且可撤销的令牌，不会持有其他内容。

状态：候选发布版。 M1 至 M7 已合并：配置、SQLite 存储、带 TOTP 的操作员身份、OAuth 2.1 授权服务、MCP 工具层、托管的 bw serve 后端、审计跟踪、打包和 Azure 模板。M8（强化安全性和兼容性验证）正在进行中。可选且默认关闭的操作层已完成至 M14：M9 引擎、操作员页面和 http 连接器；M10 Microsoft Graph 凭据适配器；M11 sql；M12 ssh；M13 winrm；以及 M14 策略表单验证消息、调用历史和写入视图，以及从已连接客户端列表管理授权。M16 新增了 code 连接器：通过其 sidecar 对私有 GitHub 仓库进行 Semble 代码搜索（指南）。http 目标可以固定其证书，或信任私有证书颁发机构；oauth2 凭据模式可从任意 OAuth 2.0 令牌端点获取令牌（指南）。vaultgate 已取消自身的逐次调用写入确认：审批由 Agent 的客户端负责。可选的凭据中继会向已标记的 Tailscale 节点上的程序提供 bw serve 的读取 API（指南）。browser 属于 M15；请参阅 docs/PLAN.md。

原因

Agent 能读取的凭证最终会进入对话记录。 Agent 为了使用密码而将其显示出来后，该值就会留在模型的上下文、聊天记录、客户端日志，以及 Agent 构造的任何命令行中；即使撤销 Agent 的权限，也无法收回它。vaultgate 的设计目标是让 Agent 永远不需要获取该值：

• 使用，而非读取。 启用操作层后 （指南、规范 13 和 13a、ADR 0007）， Agent 只需指定你定义的目标并描述操作：HTTP 请求、SQL 查询或语句、 在 SSH 或 WinRM 主机上执行的命令，或对 GitHub 仓库执行的 Semble 搜索。 vaultgate 从 保管库获取凭证，连接到固定的目标，在你的策略范围内运行操作，从结果中清除所有注入的 值，并返回剩余内容。Agent 永远不会提供主机、URL 基址、数据库名称或凭证；它的参数 只能改变执行的内容，不能改变执行的位置或身份。
• 写入操作需两次选择启用，并在你的工作环境中审批。 写入操作需要在 授权时拥有专属范围，且目标策略必须允许此操作。是否批准每次调用由 Agent 的客户端 负责——例如，Claude Code 会在运行其权限不允许的工具前征求确认——控制台 会列出每次更改了内容的调用。
• 为少数必须读取的值提供一个经过审计的入口。 保管库工具返回元数据。 只有一个工具会返回机密值，每次调用仅返回一项中的一个字段，并且每次调用都会经过审计。
• 不会在 vaultgate 主机上运行任何内容。 没有任何工具会在任意位置运行 Agent 发送的任意内容：ssh_run 和 winrm_run 只会在一个已配置的主机上运行一条命令，并遵守你的允许列表（允许执行 任意命令的目标既需要自身标志，也需要部署级授权），且每项操作都在其目标端执行。
• Agent 只持有令牌，不持有其他任何内容。 主密码和 API 密钥仅保存在你主机上的 vaultgate 进程中；在控制台的 Vault 页面连接保管库后，这些凭证会使用你的密钥加密。
• 严格遵循标准。 OAuth 2.1、PKCE、RFC 9728 / 8414 / 8707 / 7591 / 7009 / 9207 和客户端 ID 元数据文档，均符合 MCP 授权 规范（2026-07-28）。
• 支持所有 Bitwarden 服务。 bitwarden.com、bitwarden.eu、自托管 Bitwarden 和 Vaultwarden。
• 运维简单。 一个进程、一个 SQLite 文件、结构化日志、健康 检查、审计记录。docker compose up 即可完成安装。

与其他 Bitwarden MCP 服务相比

托管式 Agent 通过 HTTPS 访问 MCP 服务，无法在你的保管库旁运行进程，而其他 Bitwarden MCP 服务正是为这种本地进程而构建的：

服务端	运行位置	主密码 / API 密钥由谁保管	客户端授权	同意与范围	撤销	审计追踪	使用凭据但不查看凭据
官方 bitwarden/mcp-server	本地，通过 stdio；其 README 指出绝不能公开托管	你的设备：客户端配置中的 bw CLI 会话（BW_SESSION），或操作系统密码对话框	无；启动该进程的任何人都可以使用	无；启动该进程的客户端可使用所有工具	锁定密码库或结束 bw 会话	未说明	未说明
warden-mcp，远程模式	你托管的长期运行 HTTP 服务	客户端；客户端在每次调用时通过 X-BW-Password、X-BW-ClientId 和 X-BW-ClientSecret 请求头发送这些凭据	未内置（“v1 中没有内置身份验证层”）	无；READONLY 和 NOREVEAL 开关对所有客户端一视同仁	轮换 Bitwarden 凭据	未说明	未说明
典型的社区服务端，例如 vaultwarden-mcp、bitwarden-mcp-server	本地 stdio，或明文 HTTP 端口	服务端进程通过环境变量获取电子邮件地址和主密码	无	无	轮换 Bitwarden 凭据	未说明	未说明
vaultgate	你的主机，可通过 HTTPS 供托管 Agent 访问	仅 vaultgate 进程保管；Agent 持有不透明令牌	内置 OAuth 2.1 授权服务器：操作员通过 TOTP 登录，支持 PKCE、RFC 9728 / 8414 / 8707 / 7591 / 7009 / 9207、客户端 ID 元数据文档	每个客户端都有单独的同意页面；vault:read、vault:reveal、vault:generate、vault:write（默认关闭）；为每个已启用连接器提供 actions:* 范围	可在控制台的 Agents 页面按客户端或令牌撤销；刷新令牌会轮换，重放会撤销整个令牌族	记录每次工具调用、登录、同意、令牌签发、刷新和撤销，并可导出	在你定义的目标上执行类型化操作：http（含 Microsoft Graph）、sql、ssh、winrm、code（Semble）
"未描述"表示项目的 README 未对此进行说明。带链接的验证说明（含日期），以及何时更适合选择官方 stdio 服务端，请参阅：docs/comparison.md。

快速开始

当前版本为 0.1.0-rc.26（package.json；版本发布会在 GitHub 上打标签）。在一台装有 Docker Engine、Compose 插件、指向该主机的 DNS 名称，且 80 和 443 端口可从互联网访问的虚拟机上：

git clone https://github.com/adamrowles1996/vaultgate.git
cd vaultgate
cp .env.example .env

在 .env 中设置 VAULTGATE_DOMAIN、VAULTGATE_PUBLIC_URL 和 VAULTGATE_VERSION，然后：

mkdir -p secrets
head -c 32 /dev/urandom | base64 > secrets/vaultgate_secret_key
touch secrets/bw_password secrets/bw_client_secret
chmod 0400 secrets/* && sudo chown 10001 secrets/*
docker compose up -d
docker compose logs -f vaultgate

首次运行时，日志会打印一个一次性 /setup?token=… URL。打开该 URL，并使用电子邮件地址、密码和身份验证器中的验证码（TOTP）创建操作员账户。该密码是 vaultgate 自己的操作员登录密码，不是 Bitwarden 主密码，也永远不会变成 Bitwarden 主密码。登录后，在 Vault 页面连接保管库：填写服务器、API key 客户端 ID 和密钥，以及主密码。vaultgate 会使用 VAULTGATE_SECRET_KEY 加密存储该连接，因此重启和升级后仍然有效。然后，将 https://<host>/mcp 添加到 Claude（或 Claude Code、Codex、MCP Inspector），作为远程 MCP 服务，并在授权页面批准所需权限范围。vaultgate 使用的 bw CLI 已包含在映像中，并由 install.sh 安装；主机上无需安装其他内容。操作说明：docs/guides/first-run.md；映像详情及验证信息：docs/guides/install-docker-compose.md。

若要让 Agent 使用凭据而不是读取凭据，请设置 VAULTGATE_ENABLE_ACTIONS=true，并启用所需各连接器对应的开关，然后重启，并在控制台的 Connections 页面添加连接（目标）：docs/guides/actions.md。

工作原理

Claude / Codex ──HTTPS + Bearer──▶ vaultgate ──loopback──▶ bw serve ──▶ Bitwarden
                 ▲                    │    │
                 │                    │    └──pinned──▶ your API, database, SSH or WinRM host
                 └── OAuth 2.1 ◀──────┘        (credential injected by vaultgate, result scrubbed)
                   (consent page, operator login with TOTP)

1. Agent 调用 /mcp，并收到 WWW-Authenticate 质询。
2. 它从受保护资源元数据中发现授权服务器，进行注册（Client ID Metadata Document、动态注册，或预注册 ID），并将你带到授权页面。
3. 你登录（密码 + TOTP）并批准权限范围：vault:read、vault:reveal、vault:generate，可选的 vault:write，以及部署启用的每个连接器的 actions:* 权限范围。
4. 获得 actions:* 权限范围后，Agent 会列出获准使用的目标并调用它们：http_request、sql_query、sql_execute、ssh_run、winrm_run，以及 Semble 连接的 code_search、code_find_related 和 code_read。vaultgate 会从保管库中获取凭据，在目标上执行操作，并返回已清理的结果；凭据绝不会传给 Agent。
5. 获得保管库权限范围后，它可以搜索条目、读取元数据、逐个揭示机密字段、生成密码，并在获得许可时创建或更新条目。

安装

vaultgate 前端始终需要终止 TLS；以下每种方法最终都会提供托管 Agent 可访问的公开 https:// 源。

方法	指南
使用 Caddy 的 Docker Compose（推荐）	docs/guides/install-docker-compose.md
Debian 或 Ubuntu 虚拟机，使用 install.sh	docs/guides/install-linux.md
使用你自己的反向代理（Caddy、nginx）	docs/guides/reverse-proxy.md

版本发布会提供适用于 linux/amd64 和 linux/arm64 的 ghcr.io/adamrowles1996/vaultgate:<version>，使用 Sigstore cosign 签名，并附带 SBOM 和来源证明，以及供脚本安装使用的 vaultgate-<version>.tgz 及其 .sha256 文件。

文档

文档	内容
docs/guides/	用户指南：首次运行、连接 Claude、Claude Code、Codex 和 Inspector、工具与权限范围、可自托管的 Bitwarden、备份、升级、安全模型、常见问题
docs/spec/	规范性规范，每个主题单独成文
docs/PLAN.md	里程碑、退出标准、风险
docs/THREAT_MODEL.md	资产、攻击者、缓解措施、剩余风险
docs/comparison.md	vaultgate 与其他 Bitwarden MCP 服务的区别，并附有注明日期的核验记录
docs/adoption.md	列表、渠道和应用商店定义，以及各项的提交流程
server.json	MCP Registry 列表；发布方式：docs/guides/publishing.md
docs/adr/	架构决策记录
CONTRIBUTING.md	开发工作流和质量门禁
SECURITY.md	漏洞报告

开发

需要 Node 26（参见 .nvmrc）和 mise，用于固定版本的外部 代码检查工具。

mise install         # actionlint, shellcheck, shfmt, hadolint, gitleaks, editorconfig-checker
npm ci
npm run dev          # runs src/main.ts directly with Node's type stripping
npm run quality      # format, every linter, types, dead code, file sizes, provenance, tests at 100%

CI 中运行的每项检查都可在本地通过 npm run quality 运行。有关仓库强制执行的规则及其原因，请参阅 CONTRIBUTING.md。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。