Vaultwarden Drop Slot

vaultwarden-drop-slot-mcp

セルフホストの Vaultwarden（Bitwarden 互換）保管庫に、書き込み専用で認証情報を預けるための MCP サーバー、CLI、Node.js モジュールです。 Claude Code や Codex などの AI エージェントやデプロイスクリプトは、新しいログイン情報（パスワード）やセキュアノートを、受信箱に届く前に age で暗号化して保存できます。既存のシークレットを読み取れる保管庫ログイン情報は不要です。

TL;DR

エージェントに保管庫の鍵を渡さずに、新しいパスワードを保存できます。

エージェントまたはデプロイスクリプトが認証情報を作成します。それをチャットに貼り付けたり、手作業でコピーしたり、既存のパスワードを読み取れる保管庫ログイン情報をエージェントに渡したりせずに、Vaultwarden に保存したい場合に利用できます。このプロジェクトは預け入れ専用の経路を提供します。新しいアイテムを暗号化して受信箱に渡し、受領確認を受け取ります。別の信頼されたインポーターが、それを通常のログイン情報またはセキュアノートとして保存し、既存の Bitwarden クライアントで開けるようにします。

• エージェント向け： シークレットを預け入れるツールと、配信状況を確認するツールの 2 つの 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 サーバーは io.github.ip2k/vaultwarden-drop-slot-mcp としてMCP Registryにも掲載されています。コンテナーはローカルでビルドされます。オリジナルのコードは 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 クライアント	Writer トークン、固定された公開 recipient	暗号化、預け入れ、自身の受領確認の確認
HTTPS 受信箱	トークンのハッシュ、暗号化されたキュー	認証、キューへの追加、配信状態の返却
プライベートなインポーター	age 秘密鍵、専用の保管庫セッション	復号と作成、配信確認のためのプライベートな読み取り
オプションのリモート MCP アダプター	OAuth 設定、Writer 認証情報	ユーザー認証、平文のツール引数の暗号化、預け入れの転送

Writer の機能は作成専用です。 インポーターは信頼されたコンポーネントであり、そのアカウントがアクセスできるすべての情報を読み取れます。専用の自動化アカウントを使用し、通常のアカウントとは別の共有組織を使ってください。フォルダーやコレクションは、独立した暗号学的境界ではありません。個人保管庫モードを使うには、明示的な設定によるオプトインが必要です。

HTTP MCP アダプターは、AI プロバイダーがこれらのツール引数を受け取る場合と同様に、平文を参照できます。デプロイスクリプトが生成したシークレットは、ローカル CLI に直接パイプするか、Node モジュールを呼び出してください。任意のファイルパス、URL 取得、シェル、読み取り、検索、編集、削除を行うツールはありません。

セットアップの概要

コピーして使えるコマンド、ファイル権限、TLS、オーナーのログイン、ルーティング、最初のテストについては、セットアップの完全な手順に従ってください。Linux の Docker ホスト、Compose v2、既存の 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. 専用の Vault アカウントを登録します。 組織とコレクションを作成し、インポーターをユーザーとして招待して、メンバーシップを承諾・確認し、コレクションの編集アクセスを明示的に付与します。プライベートなターミナルからログインします。
5. 保存先を設定してインポーターを起動します。 プライベート設定でライター ID を組織 UUID とコレクション 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 を実行し、生成された .tgz を npm install /absolute/path/vaultwarden-drop-slot-mcp-0.1.0.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 は Vault 内でプライベートに検証されたことを意味します。ロックされたインポーターがある場合、アイテムはキューに残ります。失敗や作成結果が曖昧な場合は、上限付きの再試行とプライベートな照合が行われます。配信の制限を参照してください。

ローカル 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"]
    }
  }
}

利用できるツールは、次の 2 つだけです。

• deposit_secret({request_id, payload})：新しいログイン情報またはセキュアノートをキューに登録します。
• deposit_status({receipt})：queued、importing、imported、failed のいずれかを返します。

新しいアイテムごとに新しい UUID を使用してください。同じ UUID を再利用できるのは、元のアイテムを再試行する場合だけです。クライアントは元の暗号化済みエンベロープをプライベートなスプールに保持します。同じリクエスト ID で引数を変更しても、何も作成または上書きされません。そのため、タイムアウト後の再試行でも、まったく同じ暗号文が使われます。再試行が不要になるまでスプールを保持してください。スプールの上限は 10,000 件です。

ツールが返すのはレシートのみです。トークンはホスト設定に保持し、プロンプト、ツール引数、チェックイン済みの MCP 設定には絶対に含めないでください。

CLI と Node モジュール

deposit コマンドは、標準入力から {request_id,payload} の JSON を読み込みます。シークレット生成ツールは、シークレットをシェル引数やファイルに入れずに、パイプでこのコマンドに渡せます。

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、アルゴリズム、承認済みのサブジェクト／クライアントのマッピングを設定してください。ディスカバリーは /.well-known/oauth-protected-resource/mcp で公開されます。ここでは認可サーバーを構築しません。

リモートのセットアップを参照してください。ホスト型アシスタントを利用するには、到達可能な HTTPS エンドポイントと、対応する OAuth プロバイダー／クライアント登録設定も必要です。ホスト型の Claude／ChatGPT へのエンドツーエンドの登録は、引き続き別途確認が必要です。

配信と運用上の制限

キューとインポーターの台帳には、完全同期を有効にしたトランザクション対応の WAL モード SQLite を使用します。インストールごとに、論理的なインポーター／台帳を 1 つだけサポートします。冪等性は、書き込み元とリクエスト UUID の組み合わせで名前空間が分けられます。ボールト内での非公開検証が完了した後にのみ、配信済みとして記録されます。

Vaultwarden とのシステム間でのアトミックなトランザクションはありません。永続化される作成インテントによって、自動作成の試行は最大 1 回に制限されます。不確定な結果は、非公開の暗号化マーカーによって照合されます。インテントを記録してから作成リクエストを送信するまでの間にプロセスが停止した場合は、オペレーターによる復旧が必要です。これは、重複作成をひそかに行うよりも、失敗またはキューに残った送信を明示することを意図的に優先しています。あらゆる状況での厳密に 1 回の配信を保証するとうたわないでください。

デフォルト値は、書き込み元ごとに UTC の 1 日あたり新規送信 100 件、書き込み元ごとに保留中 100 件、インストールごとにレシートのトゥームストーン 100,000 件、上限付きの配信試行 5 回、未配信の暗号文の保持期間 7 日間、インポート検証後の暗号文の即時削除です。ボールトがロックされている間は、保持期間が切れるまで、再試行回数の上限を消費せずにキューに残ります。トークンの有効期限切れや失効は、次のリクエストから反映されます。成功したレシートは、コンパクトな冪等性トゥームストーンとして保持されます。

脅威モデル、運用ガイド、OpenAPI コントラクト、依存関係一覧をお読みください。