Vaultwarden Drop Slot

vaultwarden-drop-slot-mcp

用于向可自托管的 Vaultwarden（兼容 Bitwarden）保险库单向存入凭据的 MCP 服务、CLI 和 Node.js 模块。 Claude Code 和 Codex 等 AI Agent，以及部署脚本，可以保存新的登录凭据（密码）和安全笔记；这些内容在到达收件箱前会使用 age 加密，且无需提供能够读取现有机密的保险库登录凭据。

简介

让 Agent 保存新密码，但不向它提供保险库密钥。

Agent 或部署脚本创建了一项凭据。你希望将其保存到 Vaultwarden，而不必粘贴到聊天中、手动复制，或向 Agent 提供能够读取现有密码的保险库登录凭据。本项目提供一条仅存入的路径：加密新条目，将其交给收件箱，然后收到回执。独立的可信导入器会将其保存为普通登录凭据或安全笔记，供你通过现有的 Bitwarden 客户端打开。

• **对于 Agent：**两个 MCP 工具——存入机密并查看其投递状态。
• **对于脚本：**基于 stdin 的 CLI 和带类型的 Node.js 模块。
• **对于运维人员：**可移植的 Docker 容器、自有 Vaultwarden 和专用导入器账户。无需更改 Vaultwarden。

**此限制适用于提交方。**导入器可以访问保险库；请妥善保护其账户和主机。AI 工具参数中包含的机密仍可能被 AI 提供商看到。如果脚本可以在不调用模型的情况下生成并存入机密，请直接使用 CLI 或 Node 模块。

**版本 0.1.0。**可从 npm 安装（npm install vaultwarden-drop-slot-mcp，或运行 npx -y vaultwarden-drop-slot-mcp），也可从此仓库或本地打包的 tarball 安装。此 MCP 服务也已列入 MCP Registry，名称为 io.github.ip2k/vaultwarden-drop-slot-mcp。容器在本地构建。原始代码采用 Apache-2.0 许可证。这是一个独立项目，与 Bitwarden 或 Vaultwarden 均无关联。有关已测试的行为和限制，请参阅验证记录。

从这里开始：设置指南 · MCP 连接 · 运维 · 安全设计

从新凭据到保险库

flowchart TB
    producer["Agent or deployment script"]
    client["Local MCP, CLI or Node client<br/>Encrypt with pinned age public key"]
    inbox["HTTPS inbox<br/>Store ciphertext and receipt state"]
    importer["Private importer<br/>Decrypt with age private key"]
    vault["Vaultwarden<br/>Dedicated organization and collection"]
    owner["You<br/>Existing Bitwarden clients"]
    producer -->|New login or secure note| client
    client -->|Ciphertext plus writer authentication| inbox
    importer -->|Claim encrypted job| inbox
    inbox -->|Ciphertext job| importer
    importer -->|Create and privately verify| vault
    vault -->|Normal vault sync| owner
    importer -.->|Verified delivery acknowledgment| inbox
    inbox -.->|Opaque receipt and status only| client
    classDef publicSide fill:#e8f1ff,stroke:#315f99,color:#122842
    classDef privateSide fill:#e7f4ec,stroke:#36704a,color:#173422
    class producer,client,inbox publicSide
    class importer,vault,owner privateSide

收件箱无法解密负载。只有私有导入器持有 age 身份和专用的 Bitwarden CLI 会话。公共 API 不提供读取、搜索、列出、编辑或删除保险库内容的操作。条目 URL 以文本形式存储；服务绝不会获取这些 URL。

工作方式

组件	持有内容	可执行操作
本地 MCP / CLI / Node 客户端	写入令牌、固定的公共接收方	加密、存入、查看自己的回执
HTTPS 收件箱	令牌哈希、加密队列	验证身份、将内容加入队列、返回投递状态
私有导入器	age 私钥、专用保险库会话	解密并创建条目；私下读取以验证投递
可选的远程 MCP 适配器	OAuth 配置、写入凭据	验证用户身份、加密明文工具参数、转发存入请求

**写入能力仅限创建。**导入器是可信的，可以读取其账户能够访问的所有内容。请使用专用自动化账户，并与常用账户分属不同的组织。文件夹或集合不是独立的加密边界。个人保险库模式需要显式选择加入配置。

HTTP MCP 适配器会看到明文，接收这些工具参数的 AI 提供商也一样。对于部署脚本生成的机密，请通过管道直接传给本地 CLI，或调用 Node 模块。此项目不提供任意文件路径、URL 获取、Shell、读取、搜索、编辑或删除工具。

设置概览

请按照完整设置指南操作，其中提供了可复制的命令、文件权限、TLS、所有者登录、路由和首次测试说明。指南假设你使用配备 Compose v2 的 Linux Docker 主机，并且已有一个通过 HTTPS 访问的 Vaultwarden 实例；本地客户端/模块需要 Node.js 24.2+。镜像构建支持 amd64 和 arm64；已在 amd64 上验证运行。

1. 从源代码构建。 克隆此仓库，运行 npm ci --ignore-scripts、 npm test 和 npm run build。构建默认运行时镜像和可选的导入器镜像。 默认镜像不包含 Bitwarden CLI。
2. 创建私有部署目录。 生成注册材料，并拆分生产端、收件箱和导入器文件。请将该目录放在检出目录之外。
3. 配置 TLS 并启动收件箱。 使用客户端和导入器信任的证书。只公开 HTTPS 接收端口；工作器端口应保持私有。
4. 注册专用保险库账户。 创建组织和集合，邀请导入器作为 User，接受并确认成员资格，然后明确授予集合编辑权限。从私有终端登录。
5. 设置目标位置并启动导入器。 在私有配置中，将写入器 ID 映射到组织和集合 UUID。
6. 测试，然后连接 MCP。 存入一个模拟条目，等待状态变为 imported，然后在常用的 Bitwarden 客户端中打开该条目。接着按照特定客户端的 MCP 说明操作。

git clone https://github.com/ip2k/vaultwarden-drop-slot-mcp.git
cd vaultwarden-drop-slot-mcp
npm ci --ignore-scripts
npm test
npm run build
node dist/cli.js --help

对于 Node 应用，运行 npm install vaultwarden-drop-slot-mcp。若要改用本地构建版本，请在此处运行 npm pack，然后通过 npm install /absolute/path/vaultwarden-drop-slot-mcp-0.1.0.tgz 安装生成的 .tgz 文件。

回执的含义

sequenceDiagram
    participant P as Producer
    participant I as Encrypted inbox
    participant W as Private importer
    participant V as Vaultwarden
    P->>I: Encrypted item and request UUID
    I-->>P: Opaque receipt (queued)
    W->>I: Claim job
    I-->>W: Ciphertext (importing)
    Note over W: Decrypt, check destination, record intent
    W->>V: Create item with private submission marker
    W->>V: Verify marker in the selected destination
    V-->>W: Matching item
    W->>I: Acknowledge verified import
    Note over I: Delete queued ciphertext and retain receipt
    P->>I: Check own receipt
    I-->>P: imported
    Note over P,I: Same UUID means same ciphertext<br/>and the same receipt

queued 表示收件箱已接收；imported 表示已在保险库中私下验证。导入器处于锁定状态时，任务会继续排队。失败和创建状态不明确的情况会使用有限次数的重试和私下对账；请参阅投递限制。

本地 MCP

完成设置后，配置 MCP 客户端，使其通过私有生产端配置文件启动可执行文件。请使用绝对路径；以下路径仅为示例。Claude Code、Codex、桌面客户端、Docker stdio 和远程 HTTP 的说明，请参阅 MCP 连接：

{
  "mcpServers": {
    "vaultwarden-drop-slot": {
      "command": "node",
      "args": ["/absolute/path/to/dist/cli.js", "stdio", "/private/path/client.json"]
    }
  }
}

目前恰好提供两种工具：

• deposit_secret({request_id, payload})：将新的登录信息或安全备注加入队列。
• deposit_status({receipt})：返回 queued、importing、imported 或 failed。

每个新条目都使用一个全新的 UUID。仅在重试原始条目时复用 UUID。客户端会在其私有暂存区中保留原始加密信封；使用相同请求 ID 但参数已更改，不会创建或覆盖任何内容。因此，超时后重试会使用完全相同的密文。请保留暂存区，直到不再需要重试；其上限为 10,000 个条目。

工具只返回回执。请在主机配置中保留令牌；切勿将令牌放入提示词、工具参数或已纳入版本控制的 MCP 设置中。

CLI 和 Node 模块

deposit 命令从 stdin 读取 {request_id,payload} JSON。机密生成器可以通过管道将数据传给该命令，而无需将机密放入 shell 参数或文件中：

your-secret-generator | node dist/cli.js deposit /private/path/client.json
node dist/cli.js status /private/path/client.json RECEIPT_UUID

npm 模块导出类型化的 DepositClient、seal、fingerprint、验证模式和协议类型。以下示例展示了如何在自己的部署程序中使用：

import { DepositClient } from 'vaultwarden-drop-slot-mcp';

const client = new DepositClient(enrolledClientConfig);
const receipt = await client.deposit(persistedRequestId, {
  type: 'login',
  name: 'New service',
  username: generatedUsername,
  password: generatedPassword,
  urls: ['https://service.example.com'],
});
// Only the receipt is safe to log.
console.log(receipt);

prepare() 会写入仅含密文的暂存条目；submit() 会发送该确切信封。应用可以分别使用这两个方法，以实现自己的重试逻辑。负载中的 URL 会作为数据存储，绝不会被获取。

远程 MCP

mcp-http remote.json 通过原生 HTTPS 在 /mcp 提供无状态的 Streamable HTTP。它需要现有的 OAuth 授权服务器、绑定受众的 JWT 访问令牌、过期时间、client_id 和 sub 声明，以及 deposits:write 和 deposits:status 两个作用域。配置颁发者、JWKS URL、算法以及获准的 subject/client 映射；发现端点位于 /.well-known/oauth-protected-resource/mcp。此处不会构建授权服务器。

参见远程设置。托管式助手还需要可访问的 HTTPS 端点，以及受其支持的 OAuth 提供方／客户端注册配置。端到端的托管 Claude/ChatGPT 接入仍需单独验证。

交付与运行限制

队列和导入记录账本使用处于 WAL 模式且启用完整同步的事务型 SQLite。每个安装仅支持一个逻辑导入器／记录账本。幂等性按写入方和请求 UUID 命名空间隔离。只有在保管库中完成私密验证后，交付才会标记为已导入。

与 Vaultwarden 之间不存在跨系统原子事务。持久化的创建意图可确保自动创建尝试最多一次；结果不明确时，会通过私密加密标记进行核对。如果进程在记录意图后、发送创建请求前终止，则需要操作员恢复。此设计有意优先显示失败／排队的提交，而不是静默创建重复项。不要声称可在任何情况下保证恰好交付一次。

默认值：每个写入方每天（UTC）最多新建 100 个存款，每个写入方最多 100 个待处理存款，每个安装最多保留 100,000 个回执墓碑，最多进行五次有界交付尝试，未交付密文保留七天，并在验证导入后立即删除密文。保管库锁定时，项目会继续排队且不消耗重试额度，直至保留期结束。令牌过期／撤销会在下次请求时生效。成功回执会作为精简的幂等性墓碑保留。

请阅读威胁模型、运维指南、OpenAPI 契约和依赖清单。