Bitwarden Public API and Secrets Manager (unofficial)

Bitwarden MCP サーバー

非公式です。 このプロジェクトは Bitwarden Inc. が作成したものではなく、同社と提携または承認されているものでもありません。 「Bitwarden」は Bitwarden Inc. の商標です。詳細は NOTICE をご覧ください。

Bitwarden の Public API（組織管理）と Bitwarden Secrets Manager（公式 SDK を介したプロジェクトとシークレット）を、型付きの読み取り・書き込みツールとして提供する、ローカルの Model Context Protocol（stdio） サーバーです。

想定される用途：AI アシスタントが、メンバー、グループ、コレクション、ポリシー、ライセンス枠、Secrets Manager のデータを単一のホストから管理できる、管理者向け MCP です。セルフホストの Bitwarden インスタンス、公式 Bitwarden Cloud、またはその両方での利用を想定して設計されています。

クイックリンク： アーキテクチャ · コントリビューション · セキュリティポリシー · リリース · 変更履歴 · Issue

メンテナンス状況

• 1 人のメンテナー (@mguttmann) が空き時間に、可能な範囲でメンテナンスしています。作者は本番環境で使用しています。サポート契約はなく、応答時間も保証されません。
• 機能追加よりセキュリティ修正を優先します。脆弱性は SECURITY.md の説明に従って非公開で報告し、公開 Issue では報告しないでください。
• 依存関係の更新は Dependabot が行います。実行時の依存関係に既知の勧告がある場合、CI は失敗します。
• 修正が提供されるのは最新のマイナーリリースのみです。
• Issue とプルリクエストを歓迎します。CONTRIBUTING.md をご覧ください。

機能

• Public API： メンバー、グループ、コレクション、ポリシー、イベント、組織のインポート、サブスクリプション／ライセンス。
• Secrets Manager： 公式の @bitwarden/sdk-napi を介したプロジェクトとシークレット（ゼロ知識暗号化。平文の名前と値を直接返します）。
• 2 つのインスタンスに対応： セルフホストの Bitwarden インスタンス、公式クラウド、またはその両方に対して実行できます。登録時にツールをそれぞれのインスタンスに紐付けるため、誤ったルーティングが偶発的に起きることはありません。
• 一般的な操作フローに対応する手書きのツール（bw_member_list、 bw_license_subscription_get、bws_secret_get_value、…）に加え、 bw_raw_request という代替手段もあります。セルフホスト環境とクラウドの両方を設定した場合、サーバーは Secrets Manager の有無にかかわらず 54 個のツールを一覧表示します。ツール名と必須パラメーターは tests/tool-contract.test.ts で固定されており、パラメーターは追加（任意）のみ可能で、削除や名前変更は行われません。
• 配布パッケージには生成ツールが含まれません： bw_<resource>_<op>_raw ツール用のジェネレーターは存在します（npm run generate）が、配布される仕様（specs/public-api.spec.json）は空のため、生成ツールは 0 個登録されます。生成された raw ツールをご覧ください。
• 確認を必須とする書き込み： すべての書き込みツールは、confirm: "YES" を指定せずに呼び出すと、リクエストのプレビューを返します。既定では有効です。モデル自身が confirm を設定するため、これは手間を増やす仕組みであってセキュリティ境界ではありません（安全性モデルをご覧ください）。
• 設計上、シークレットを安全に扱います： メタデータ一覧で値が返されることはありません。アクセストークンは Web ボルト内でのみ管理されます。
• トークン予算を考慮した一覧の既定値： 一覧ツール（bw_member_list、 bw_collection_list、bw_group_list、bw_event_query）は、LLM のツール呼び出しにおけるトークン予算内に収まるよう、既定で簡潔な形式のデータを返します。完全なネスト形式のレスポンスを選択する方法は、一覧レスポンスの形式をご覧ください。

この MCP でできること、できないこと

Bitwarden の API は、認証と暗号化の要件が異なるさまざまな機能を提供しています。この MCP は、問題なくアクセスできる機能をすべてラップしています。一部の操作では Bitwarden の暗号化レイヤーが必要なため（公式 SDK を使用します）、公開 API がない操作では Web ボルトが必要です。

できること：公開 API（組織とメンバー）

Organization Public-API キー（organization.<uuid> / client_credentials / scope api.organization）を使用します。

• 組織メンバーの一覧表示、取得、招待、更新、削除
• グループの作成、更新、削除、グループメンバーの管理
• グループごとのコレクションアクセス権（読み取り／パスワードを非表示／管理）の更新。 更新ツールで省略したフィールドは現在の値を保持します
• 組織ポリシーの読み取り、設定
• イベントログの照会
• グループとメンバーの一括インポート
• サブスクリプションの詳細情報全体の読み取り（PM シート、SM シート、ストレージ、 サービスアカウントの枠数）
• 統合エンドポイント PUT /public/organization/subscription を使用した、PM シート、PM ストレージ、SM シート、SM サービスアカウント枠数の調整。ツールは増減値を受け取り、現在値に増減値を加えた値を新しい合計として送信し、その値を再取得します
• クラウドのみ：クラウド組織のライセンス情報の確認

できること：Secrets Manager（公式 Bitwarden SDK 経由）

Machine-Account アクセストークン（BWS_ACCESS_TOKEN）を使用し、 Bitwarden のゼロ知識暗号化を処理する @bitwarden/sdk-napi を介して交換します。

• 設定済みの MA から閲覧できるプロジェクトの一覧表示、取得、作成、更新、削除
• シークレットのメタデータの一覧表示、クリアテキスト値を含むシークレット全体の取得、作成、 更新、削除

できないこと：Web ボルトで人間が操作する必要があります

これらは、このサーバーが使用する認証情報（組織 API キー、Machine Account アクセストークン）では利用できません。SDK と bws CLI でも利用できません。

• Machine Account の作成、更新、削除
• Machine Account へのプロジェクトの割り当て
• Machine Account Access Token の作成、ローテーション
• 組織内のすべての Machine Account の一覧表示 （Machine Account とアクセストークンを管理できるのは、Web ボルトにログインしたユーザーのみです）
• クラウドからセルフホストへのライセンス再同期の実行
• メンバーの Secrets Manager アクセス権の読み取り、付与、取り消し。Bitwarden の Public API は accessSecretsManager を返すことも適用することもできません。 bw_member_grant_sm／bw_member_revoke_sm は登録されたままですが、常にエラーを返します。
• ユーザーごとのコレクションアクセス権（bw_collection_update は空でない users リストを拒否します。メンバーに直接アクセス権を付与するには bw_member_update の collections を使用してください）、グループの accessAll（上流で削除済み）、IP アドレスによるイベントのフィルタリング

これらすべての操作には、https://<your-host>/#/sm/{orgId}/ の Web ボルトを使用してください。

要件

• Node.js 22.12 以降（engines.node >=22.12。CI では 22、24、26 でテストします）。
• 少なくとも 1 つのインスタンス（セルフホストまたはクラウド）用の Bitwarden Public-API キー（client_id／client_secret）。
• Secrets Manager を使用する場合：Machine-Account アクセストークン（Web ボルトから取得）。

プラットフォームのサポート

この MCP は、Node.js 22.12 以降を搭載したすべてのプラットフォームで、すべての Public API 機能（メンバー、グループ、コレクション、ポリシー、イベント、 ライセンス調整）を利用できます。

Secrets Manager 機能（bws_project_*、bws_secret_*）は @bitwarden/sdk-napi（1.0.0、オプションの依存関係で、MIT ライセンスではありません）に依存しており、 このパッケージはプラットフォームごとのオプションパッケージとしてネイティブの Rust バイナリを提供します。ロックファイルには、@bitwarden/sdk-napi-darwin-arm64、-darwin-x64、 -linux-x64-gnu、-win32-x64-msvc が含まれています。

OS / アーキテクチャ	SDK バイナリ	SM ツール
macOS Apple Silicon	利用可能	利用可能
macOS Intel	利用可能	利用可能
Linux x86_64（glibc）	利用可能	利用可能
Windows x86_64	利用可能	利用可能
Linux ARM64（Raspberry Pi、AWS Graviton）	利用不可	スタブ
Linux Musl / Alpine	利用不可	スタブ
その他	利用不可	スタブ

サポート対象外のプラットフォームでも MCP は起動し、すべての Public API ツールは 通常どおり動作します。bws_project_* と bws_secret_* ツールは 登録されたままになり、呼び出し時に「この プラットフォームでは Secrets Manager SDK を利用できません」と返します。読み込みエラーは起動時に一度、 warn 行としてログに記録されます。

Bitwarden が新しいプラットフォーム向けのバイナリを含む SDK バージョンをリリースした場合は、 依存関係とロックファイルを更新するだけで取り込まれます。コードの変更は 不要です。

インストール

このパッケージは npm の the-real-bitwarden-mcp で、provenance を付けて GitHub Actions から公開されています。その bin は bitwarden-mcp です。どの方法でも設定は同じです（ 設定を参照）。

ローカルの MCP クライアント（npx または npm install）

npx はパッケージを取得して起動します。更新を再起動時の 副作用ではなく意図的な判断にするため、バージョンを固定してください。

npx -y the-real-bitwarden-mcp@<version>

または、一度インストールして bin を起動します。

npm install -g the-real-bitwarden-mcp@<version>
bitwarden-mcp

クライアント設定については、コネクターの接続設定を参照してください。

ゲートウェイとサーバー（npm からバージョンを固定してインストール）

ロックファイルを使ってバージョンを固定してインストールし、npx や インストールスクリプトを使わずに node で起動します。空のディレクトリで一度だけ実行します。

npm init -y
npm install --save-exact the-real-bitwarden-mcp@<version>   # writes package-lock.json

package.json と package-lock.json をコミットするか、保持してください。デプロイごとに次を実行します。

npm ci --omit=dev --ignore-scripts
node --env-file=/path/to/.env node_modules/the-real-bitwarden-mcp/dist/index.js

このパッケージにはインストールスクリプトも、devDependencies に含まれる実行時依存関係もありません。そのため、--omit=dev --ignore-scripts で完全にインストールできます。 Secrets Manager SDK バイナリはプラットフォームごとのオプションパッケージで、npm が OS と CPU に応じて選択します。これにもスクリプトは不要です。

ソースから

git clone https://github.com/mguttmann/the-real-bitwarden-mcp.git
cd the-real-bitwarden-mcp
npm ci               # also pulls the platform-specific SDK binary
cp .env.example .env
# Fill in .env, see "Configuration".
npm run build
node --env-file=.env dist/index.js

SDK バイナリはオプションの依存関係です。サポート対象外のプラットフォームでも npm ci は成功します（バイナリが存在しないだけで、SM ツールは 「利用できません」という明確なメッセージを返します）。

生成される raw ツール

npm run refresh-spec はセルフホストインスタンスの Swagger ドキュメントを specs/public-api.spec.json に取得し、npm run generate はそこから操作ごとに bw_<resource>_<op>_raw ツールを 1 つ生成します。同梱されている仕様は空のため（{"paths": {}}）、通常のビルドでは生成されるツールは 0 個です。 ツールを生成するとツール一覧が変わります。ツールの構成を固定するゲートウェイの背後でサーバーを実行している場合は、これをデプロイ時の変更として扱ってください。

設定

すべての値は環境変数です。プロセス環境から取得されます （たとえば、node --env-file=.env や MCP クライアント設定の env ブロックなど）。サーバーを --env-file （または --env-file-if-exists）を指定せずに起動した場合、 プロセスの作業ディレクトリにある .env ファイルも読み込まれ、 すでに設定されている変数を上書きせず、未設定の変数にのみ値を設定します。 --env-file を指定した場合は無視されます。 少なくとも 1 つのインスタンスを完全に設定する必要があります。そうでない場合、 サーバーは起動を拒否します。一部の変数（4 つのうち 1 つ以上）が未設定の インスタンスもエラーになります。また、API ベース URL または ID URL が http:// または https:// の URL ではない場合や、クエリまたはフラグメントが 含まれている場合もエラーになり、エラーメッセージには変数名が表示されます。 オプションの数値変数およびブール値変数に無効な値が設定されている場合は、 デフォルト値が使用されます。

変数	必須となる条件	用途
BITWARDEN_SELFHOST_API_BASE	セルフホストモード	https://vault.example.com/api
BITWARDEN_SELFHOST_IDENTITY_URL	セルフホストモード	https://vault.example.com/identity
BITWARDEN_SELFHOST_CLIENT_ID	セルフホストモード	Public-API クライアント ID（organization.{orgId}）
BITWARDEN_SELFHOST_CLIENT_SECRET	セルフホストモード	Public-API クライアントシークレット
BITWARDEN_CLOUD_API_BASE	クラウドモード	https://api.bitwarden.com
BITWARDEN_CLOUD_IDENTITY_URL	クラウドモード	https://identity.bitwarden.com
BITWARDEN_CLOUD_CLIENT_ID	クラウドモード	Public-API クライアント ID（クラウド）
BITWARDEN_CLOUD_CLIENT_SECRET	クラウドモード	Public-API クライアントシークレット（クラウド）
BWS_ACCESS_TOKEN	SM ツール	マシンアカウントのアクセストークン（3 部構成の形式。下記参照）。形式が不正な場合はエラーになります
BWS_API_BASE	SM ツール（任意）	デフォルトはセルフホスト API ベース URL
BWS_IDENTITY_URL	SM ツール（任意）	デフォルトはセルフホスト ID URL
BWS_ORG_ID	SM のプロジェクト／シークレットツール	organizationId が渡されない場合に使用される組織 UUID
BITWARDEN_CONFIRM_WRITES		デフォルトは true：confirm: "YES" が指定されない限り、書き込みツールはプレビューを返します
BITWARDEN_READ_ONLY		デフォルトは false。true の場合：書き込みツールは一覧に表示されたままですが、実行は拒否されます
LOG_LEVEL		debug | info | warn（デフォルト）| error
HTTP_TIMEOUT_MS		デフォルトは 30000。API および OAuth トークンのリクエストに適用されます。各 bws_* 呼び出しに 1 つの期限が設定されます
PAGINATION_MAX_ITEMS		デフォルトは 1000
PAGINATION_MAX_PAGES		デフォルトは 20
BW_MCP_MAX_LIST_RESPONSE_BYTES		デフォルトは 60000。このサイズを超える一覧レスポンスに note 警告を追加します
BW_MCP_MAX_RESPONSE_BYTES		デフォルトは 1048576。このサイズを超える正常なツール出力は切り詰められます（「制限」を参照）

モードの一覧

BITWARDEN_SELFHOST_*	BITWARDEN_CLOUD_*	結果
present	absent	Public-API の運用ツールと SM ツールが登録されます。ライセンスツールは登録されません。bw_raw_request(instance:"cloud") は拒否されます。
absent	present	ライセンスツールと raw cloud リクエストのみ使用できます。
present	present	すべてのツールグループが登録されます。
absent	absent	サーバーの起動に失敗します。

Secrets Manager アクセストークンの取得

1. セルフホストの Vault で、Secrets Manager > Machine accounts を開き、 マシンアカウントを作成します（mcp-bitwarden のような中立的な名前がおすすめです）。
2. MCP に管理させるプロジェクトへのアクセス権をマシンアカウントに付与します。
3. マシンアカウントのアクセストークンを作成し、平文の値を .env の BWS_ACCESS_TOKEN にコピーします。
4. BWS_ORG_ID に組織の UUID も設定します（Web Vault の組織 URL から取得できます）。
5. MCP を再起動すると、bws_* ツールが使用可能になります。

それまでは SM ツールは登録されたままですが、「Secrets Manager not configured」 を返すため、利用可能な機能として確認できます。

BWS_ACCESS_TOKEN の形式

アクセストークンは . と : で区切られた3つの部分からなる形式です。

0.{ACCESS_TOKEN_UUID}.{CLIENT_SECRET}:{ENCRYPTION_KEY}

例（すべて架空の値です）：

0.aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa.BBBBBBBBBBBBBBBBBBBBBBBBBBBBBB:CCCCCCCCCCCCCCCCCCCCCC==

MCP はこのトークンを Bitwarden SDK に直接渡し、認証情報の解析と暗号化処理はすべて SDK が内部で行います。

部分	値	用途
セグメント 1	0	バージョンのプレフィックス
セグメント 2	{ACCESS_TOKEN_UUID}	SDK が OAuth の client_id として使用
セグメント 3（:より前）	{CLIENT_SECRET}	SDK が OAuth の client_secret として使用
:より後	{ENCRYPTION_KEY}	SDK がペイロードを復号します。サーバーには送信されません。

ID サーバーへの OAuth リクエストでは、scope=api.secrets（api.organization ではありません）を使用します。組織の Public-API キー（api.organization スコープの organization.* client_id）では、Secrets Manager エンドポイントにアクセスできません。これは仕様であり、バグではありません。

セルフホスト版 Bitwarden：Secrets Manager の利用可否

現在のセルフホスト版 Bitwarden（server 2026.x）では、Secrets Manager API は標準の bitwarden-api コンテナ内に含まれています。独立した sm-api コンテナはなく、bwdata/config.yml に enable_secrets_manager の切り替え設定もありません。docker-compose.yml に sm-api サービスが表示されない場合、それは正しく、想定どおりです。

Web Vault で有効なアクセストークンを使ってマシンアカウントを作成すれば、SM エンドポイントにアクセスできるようになります。

リストのレスポンス形式

4 つのリストツール（bw_member_list、bw_collection_list、 bw_group_list、bw_event_query）は、デフォルトで簡易プロジェクションを返します。Bitwarden の Public API は、各リスト項目に権限グラフ全体を埋め込むため、レスポンスが数倍に膨れ上がり、組織の規模がそれほど大きくなくても LLM ツール呼び出しのトークン予算を超えてしまうためです。

デフォルトのフィールド：

ツール	デフォルトのフィールド
bw_member_list	id、email、name、type、status、twoFactorEnabled
bw_collection_list	id、externalId
bw_group_list	id、name、externalId
bw_event_query	start／end を省略した場合、過去 24 時間がデフォルトになります

完全なレスポンスを取得するには、include パラメーター（ネストされたフィールドの許可リスト）を渡します。

{ "include": ["collections", "groups"] }   // member list with nested data
{ "include": ["all"] }                     // full Bitwarden response

項目ごとの詳細には、専用の詳細エンドポイント（bw_member_get、bw_collection_get、bw_group_get、bw_member_get_groups、bw_group_get_members）を使用します。

レスポンスサイズガードは、BW_MCP_MAX_LIST_RESPONSE_BYTES 文字を超えるリストレスポンスに note フィールドを追加します（デフォルト値は上の表を参照）。この注記はヒントにすぎません。レスポンスが BW_MCP_MAX_RESPONSE_BYTES も超える場合は、「制限」の説明に従って切り詰められ、注記は切り詰め後のレスポンスに残ります。

制限

値は src/limits.ts に定義されており、tests/docs-numbers.test.ts でこのセクションの値を検証しています。

• レスポンスサイズ。 ツールの実行が成功しても、結果が BW_MCP_MAX_RESPONSE_BYTES（バイト単位、デフォルトは 1048576）を超える場合、エラーにはせず切り詰めます。結果は有効な JSON のままです。最大のリストの先頭の項目を残し、responseTruncated オブジェクト（originalBytes、limitBytes、cutArray、keptItems、totalItems、クエリを絞り込む方法やページ分割する方法に関する hint を含む）を添えます。ルートがリストの結果はオブジェクトになり、残した項目は responseTruncated と並ぶ items に移されます。切り詰められたリストの隣にある continuationToken は削除されます（continuationTokenRemoved: true）。これは、切り詰められた項目の後から再開することになるためです。プレビューなど、リストを含まない出力は responseTruncated オブジェクトだけに置き換えられます。エラー結果はここでは切り詰めません。上流のエラーテキストは別途短縮されます。
• 入力サイズ。 引数内のいずれかの文字列が 102400 バイト（100 KiB）を超える場合、またはいずれかの配列の項目数が 10000 を超える場合（たとえば、bw_org_import のメンバー数またはグループ数が 10000 を超える場合）、送信前にツール呼び出しを拒否します。エラーにはパラメーターのパスとサイズが記載されますが、値は含まれません。
• トークンのバックオフ。 1 つのクライアント（セルフホスト、クラウド、Secrets Manager REST、Secrets Manager SDK ログイン）でトークン要求が 3 回連続して失敗すると、新しいトークン要求は 30 秒間停止します。一時停止中の呼び出しは identity backoff: ... retry after N s ですぐに失敗します。成功するとカウントはリセットされ、一時停止の直後に失敗すると次の一時停止が始まります。

実行

npm start              # production: dist/index.js (stdio)
npm run dev            # development: tsx src/index.ts (stdio)
npm test               # unit tests with mocked HTTP
npm run test:contract  # tool contract and protocol versions only
npm run test:live      # opt-in live smoke tests (read-only, RUN_LIVE_TESTS=1)
npm run inspector      # open the MCP Inspector against the built bundle

コネクターの設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または各プラットフォームに対応するファイルに追加します。npm を使用する場合：

{
  "mcpServers": {
    "bitwarden": {
      "command": "npx",
      "args": ["-y", "the-real-bitwarden-mcp@<version>"],
      "env": {
        "BITWARDEN_SELFHOST_API_BASE": "https://vault.example.com/api",
        "BITWARDEN_SELFHOST_IDENTITY_URL": "https://vault.example.com/identity",
        "BITWARDEN_SELFHOST_CLIENT_ID": "organization.<uuid>",
        "BITWARDEN_SELFHOST_CLIENT_SECRET": "<client secret>"
      }
    }
  }
}

ソースをチェックアウトしている場合：

{
  "mcpServers": {
    "bitwarden": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/the-real-bitwarden-mcp/.env",
        "/absolute/path/to/the-real-bitwarden-mcp/dist/index.js"
      ]
    }
  }
}

--env-file の代わりに、変数を args の隣の env オブジェクトに入れることもできます。どちらも設定しない場合、サーバーが .env を見つけられるのはクライアントの起動時の作業ディレクトリのみです。通常、これはリポジトリではないため、サーバーは「No Bitwarden instance configured」で終了します。

Claude Code

claude mcp add（ユーザーまたはプロジェクトのスコープ）でサーバーを登録するか、プロジェクトのルートにある .mcp.json ファイルに同じ mcpServers ブロックを追加します。

claude mcp add bitwarden -- node --env-file=/absolute/path/to/.env /absolute/path/to/dist/index.js

ゲートウェイとヘッドレスでの使用

サーバーは stdio のみで MCP を通信し、ターミナルは不要です。ゲートウェイまたはスーパーバイザーが固定された npm パッケージをインストールし（ゲートウェイとサーバーを参照）、node --env-file=/path/to/.env node_modules/the-real-bitwarden-mcp/dist/index.js で起動するか、ソースのチェックアウトをビルドします。

npm ci --no-audit --no-fund && npm run build
node --env-file=/path/to/.env /path/to/dist/index.js

• ログは stderr に JSON 行として出力されます（pino、レベルは LOG_LEVEL）。stdout には MCP ストリームのみが出力されます。
• プロトコルのリビジョン： initialize で 2025-06-18 または 2025-11-25 を指定して接続するクライアントには、そのリビジョンが使用されます。2026-07-28 のリビジョン（server/discover）で接続するクライアントには、2026-07-28 が使用されます。tests/protocol-versions.test.ts で固定されています。
• メッセージサイズの上限： MCP SDK の stdio トランスポートが受け付ける受信行（各行は 1 つの JSON-RPC メッセージ）の最大サイズは 10 MiB です。これを超える行を受信するとトランスポートが閉じます。サーバーは error 行をログに記録してコード 1 で終了し、クライアントはサーバーを再起動する必要があります。
• ツール名は安定しています。 ツール名、パラメーター名、必須パラメーターは変更されず、ツールやパラメーターが削除されることもありません。ツールに新しいオプションのパラメーターが追加される場合はあります。呼び出し元が認識できる変更は、変更履歴の「動作の変更」に記載されています。scripts/container-smoke.sh は、ゲートウェイと同じ方法でサーバーをビルドして検証します（CONTRIBUTING を参照）。
• ユーザーの分離はありません： 呼び出し元はすべて、設定されたキーの完全な権限で操作します。ゲートウェイで各ユーザーが呼び出せるツールを制限してください（SECURITY.md を参照）。

ツールリファレンス

MCP 内から bw_help を実行すると、カテゴリ別の最新カタログを取得できます。簡単な一覧は次のとおりです。

Public API：運用（セルフホスト）

• bw_member_list、bw_member_get、bw_member_invite、bw_member_update、 bw_member_remove、bw_member_reinvite、bw_member_get_groups、 bw_member_set_groups、bw_member_grant_sm、bw_member_revoke_sm （最後の 2 つは常にエラーを返します。「できないこと」を参照）
• bw_group_list、bw_group_get、bw_group_create、bw_group_update、 bw_group_delete、bw_group_get_members、bw_group_set_members
• bw_collection_list、bw_collection_get、bw_collection_update、 bw_collection_delete
• bw_policy_list、bw_policy_get、bw_policy_set
• bw_event_query
• bw_org_import

知っておくと便利なオプションパラメーター：

• bw_member_invite：permissions は、タイプ 4 のメンバーに対するカスタムロールのフラグを設定します（accessEventLogs、manageUsers、...。指定されていないフラグは false になります）。
• bw_member_update：email と name は、招待を承諾済みのメンバーのメールアドレスと名前を変更します。API はそれ以外のメンバーに対する変更を拒否します。省略した場合、変更されません。
• bw_org_import：inviteUsersAfterProvisioning: false を指定すると、新しいメンバーは招待メールなしで Staged として作成されます。deleted: true のメンバーには externalId のみが必要です。
• bw_policy_set：metadata は保存処理とともに渡されます（たとえば、ポリシータイプ 5 の defaultUserCollectionName）。ポリシーとともに保存されることはありません。
• bw_event_query：continuationToken を使うと、途中で切り詰められた結果の続きを取得できます。返されたトークンは、同じ start、end、フィルター、limit とともに渡してください。limit を指定すると、最大でその数のイベントが返されます（1 以上の整数で、PAGINATION_MAX_ITEMS を上限とします）。さらにイベントがある場合、API ページの途中で停止した場合も含め、結果は truncated: true と continuationToken を含みます。bw_member_list、bw_group_list、bw_collection_list はトークンを受け取りません。Public API はこれらのリストを 1 回のレスポンスで返します。
• truncated: true は、API が次のページを提示している間に、サーバーが PAGINATION_MAX_ITEMS または PAGINATION_MAX_PAGES に達して停止したことを意味します。最後のページが上限ちょうどで終わった場合、次のページが空になることがあります。API はそれ以上項目があるかどうかを示さずにトークンを送信し、サーバーは確認のための追加リクエストを行いません。返されたトークンで続きを取得すると、空のリストが返されることがあります。

Public API：生成された raw ツール（セルフホスト）

同梱パッケージにはありません（仕様が空です。詳しくは 生成された raw ツールを参照してください）。 src/tools/generated/snapshot.json には、現在の仕様から生成されたセットが記載されています。

ライセンス／サブスクリプション（クラウド）

• bw_license_subscription_get
• bw_license_seats_update：Password Manager のシート数（passwordManager.seats）を調整します
• bw_license_storage_update：Password Manager のストレージ（passwordManager.storage）を調整します
• bw_license_sm_seats_update：Secrets Manager のシート数（secretsManager.seats）を調整します
• bw_license_sm_service_accounts_update：Secrets Manager のサービスアカウント枠（secretsManager.serviceAccounts）を調整します

4 つとも差分値を受け取り、現在値に差分を加えた値を新しい絶対値として PUT /public/organization/subscription に送信し、サブスクリプションを再取得して、合計値が変わっていなければエラーを返します。

Secrets Manager：SDK 対応（BWS_ACCESS_TOKEN と対応プラットフォームが必要）

• プロジェクト：bws_project_list、bws_project_get、bws_project_create、 bws_project_update、bws_project_delete
• シークレット：bws_secret_list（識別子のみ）、bws_secret_get_value、 bws_secret_create、bws_secret_update、bws_secret_delete

呼び出しに organizationId が含まれていない場合、必要とするすべての bws_project_*／bws_secret_* ツールは BWS_ORG_ID を使用します。bws_secret_update では、note または projectIds が省略されると、現在のメモとプロジェクトが維持されます（最初にシークレットを読み込みます）。変更するには、それらを渡してください。マシンアカウントは、プロジェクトに属するシークレットからすべてのプロジェクトを削除できません。プロジェクトに属するシークレットに対して projectIds: [] を指定した更新は、サーバーに拒否されます。

SDK は起動時ではなく、最初の bws_* 呼び出し時に BWS_ACCESS_TOKEN でログインします。1 つの HTTP_TIMEOUT_MS の期限が bws_* 呼び出し全体に適用され、ログインと、note または projectIds を指定しない bws_secret_update の場合は現在のシークレットの読み込みも含まれます。期限に達したログインは処理を継続し、次の呼び出しは 2 つ目のログインを開始せず、その処理の完了を待ちます。タイムアウトした書き込みは、適用されている場合とされていない場合があります。

Secrets Manager：Web ボルトのみ（常にスタブ）

• マシンアカウント：bws_machine_account_list、..._get、..._create、 ..._update、..._delete、..._projects、..._grant_project、 ..._revoke_project
• アクセストークン：bws_access_token_list、..._create、..._revoke

これらはこのサーバーが使用する認証情報では利用できません。マシンアカウントとアクセストークンを管理できるのは、Web ボルトにログインしているユーザーのみです。ツールは tools/list と bw_help から確認できますが、呼び出すと常に isError: true と Web ボルトへのリンクが返されます。管理には https://<your-host>/#/sm/{orgId}/machine-accounts を使用してください。

共通

• bw_raw_request：instance パラメーター（selfhost、cloud、または sm）を指定するエスケープハッチです。 手書きのツールではカバーされない Public API または SM REST 呼び出しには、これを使用してください。 注：SM の bws_* CRUD は SDK を経由し、raw REST は経由しません。instance: "sm" を指定した raw_request は読み取り操作には引き続き使用できますが、API で暗号化された名前／値が必要なため、プロジェクトやシークレットの作成・更新には使用できません。
• bw_help：登録済みツールをグループ別にまとめたカタログです。

安全モデル

• BITWARDEN_CONFIRM_WRITES=true（デフォルト）：書き込みツールは、confirm: "YES" を指定して呼び出さない限り、プレビューを返します。**これはモデル自身による確認であり、セキュリティ境界ではありません。**モデルは最初の呼び出しでも confirm: "YES" を送信するかどうかを判断し、Bitwarden のデータ内のテキストがその判断を誘導する可能性があります。bws_secret_get_value を含む読み取り専用ツールには、この制限は適用されません。設定したキーとマシンアカウントが実行できる操作、および各ユーザーが呼び出せるツールを制限してください。
• BITWARDEN_READ_ONLY=true（デフォルトは false）：書き込みツールは名前とスキーマを維持しますが、confirm: "YES" を指定しても実行を拒否し、bw_raw_request は GET のみを許可します。確認ゲートとは異なり、モデルがこの設定を解除することはできません。
• どちらのスイッチも、大文字と小文字を問わず true／false、1／0、yes／no、on／off を受け付けます。空または空白文字のみの BITWARDEN_READ_ONLY は未設定（オフ）として扱われます。それ以外の認識できない値では読み取り専用モードがオンになり、認識できない BITWARDEN_CONFIRM_WRITES では確認ゲートがオンのままになります。
• 組織 API キーはメンバーではなくシステムユーザーとして機能するため、Bitwarden はこのキーにロール階層を適用しません。bw_member_invite と bw_member_update では、Owner を作成または昇格できます。呼び出し元にこれらの操作を許可しない場合は、読み取り専用モードまたはゲートウェイルールを使用してください。
• サーバーは、Bitwarden のデータを指示ではなくデータとして扱うよう、モデルに伝える MCP 指示を送信します。これはモデルへのヒントであり、制御機能ではありません。
• bws_secret_list ツールが返すのはシークレット識別子のみです（値フィールドは含まれません）。クリアテキストの値は、bws_secret_get_value(id) を通じて一度に 1 つのシークレットのみ返されます。bws_secret_create／bws_secret_update は値を含まないメタデータを返し、確認ゲートのプレビューではシークレットの値は <redacted, N chars> と表示されます。
• クライアントに返されるログとエラーテキストは、単一のスクラバー（src/redact.ts）を通過します。そこに記載されたキー（ベアラートークン、クライアントシークレット、アクセストークン、value など）は、階層の深さにかかわらず削除され、メッセージ内のシークレットに見える部分文字列は [REDACTED] に置き換えられます。
• リダイレクトには決して従いません。また、ドットセグメントまたはエンコードされた区切り文字を含む bw_raw_request のパスと ID は拒否されます。
• bw_raw_request のエスケープハッチは、デフォルトで instance: "selfhost" を使用し、設定されていないインスタンスへの呼び出しを拒否します。
• BWS_ACCESS_TOKEN の {ENCRYPTION_KEY} 部分は SDK に渡され、認証情報としてサーバーに送信されることはありません。

トラブルシューティング

OAuth client_credentials が invalid_client を返す

client_id は BWS_ACCESS_TOKEN のセグメント 2（UUID）である必要があり、client_secret はセグメント 3（2 つ目の . と : の間）である必要があります。どちらのフィールドにも、トークン全体や暗号化キーを使用しないでください。

最も早く原因を特定するには、認証に失敗した直後に、サーバーホストで docker logs bitwarden-identity を実行してください。Duende IdentityServer のログには、試行された client_id と、クライアントが見つかったかどうかが正確に記録されます。

簡単なスモークテスト（プレースホルダーを実際の値に置き換えてください）：

# Step 1: obtain a Secrets Manager JWT
curl -sS -X POST "https://vault.example.com/identity/connect/token" \
    -d grant_type=client_credentials \
    -d "client_id={ACCESS_TOKEN_UUID}" \
    -d "client_secret={CLIENT_SECRET}" \
    -d scope=api.secrets
# Expected: HTTP 200, JSON with access_token, token_type, expires_in, scope="api.secrets"

# Step 2: list projects (replace JWT and ORG_ID)
curl -sS "https://vault.example.com/api/organizations/{ORG_ID}/projects" \
    -H "Authorization: Bearer {JWT}"
# Expected: HTTP 200, JSON with a "data" array (empty if no projects assigned)

bws_* ツールが "SDK not available on this platform" を返す

現在のプラットフォームでは @bitwarden/sdk-napi のネイティブバイナリを利用できません（上記のプラットフォームサポート表を参照）。起動時に stderr に出力される warn ログ行の smSdk.kind に理由が記録されます（module_not_found または binary_not_available）。

ログインに失敗した場合（トークンが正しくない、Identity Server に到達できないなど）は、別のツールエラー「Secrets Manager SDK login failed: ...」または「... login timed out ...」が返されます。トークンまたは URL を修正してください。次の bws_* 呼び出し時に再度ログインするか、進行中のログインを待機するため、再起動は不要です。

サポート対象外のプラットフォームでも、すべての Public-API ツール（bw_*）は通常どおり動作します。影響を受けるのは bws_project_* ツールと bws_secret_* ツールのみです。

/api/organizations/.../projects への POST が 400「Name is not a valid encrypted string」を返す

プロジェクトやシークレットの作成・更新に bw_raw_request は使用しないでください。Bitwarden の SM API では、REST レイヤーで名前と値を暗号化する必要があります。bws_* ラッパーツールは公式 SDK を経由するため、暗号化が透過的に処理されます。代わりに bws_project_create、bws_secret_create などを使用してください。

プロジェクトまたはシークレットの一覧が空の場合

bws_project_list または bws_secret_list が空の配列を返す場合、マシン アカウントの認証は成功していますが、プロジェクトが割り当てられていません。これは権限の問題であり、認証のバグではありません。

修正するには、Web 保管庫に移動し、 /#/sm/{ORG_ID}/machine-accounts/{SERVICE_ACCOUNT_ID}/projects で対象のプロジェクトをマシンアカウントに割り当ててください。

bws_project_list ツールは、空の応答を検出するとこのヒントをインラインで表示します。

セルフホスト環境での認証デバッグ

認証に失敗した後、サーバーホストで docker logs bitwarden-identity を実行してください。 Duende IdentityServer のログには、試行された client_id と失敗の正確な理由（クライアントが見つからない、またはシークレットが一致しない）が記録されます。

ライセンス

MIT です。詳細は LICENSE を参照してください。NOTICE には、MIT ライセンスの対象外となるもの、すなわち商標、任意の @bitwarden/sdk-napi 依存関係（Bitwarden SDK ライセンス契約に基づき npm からインストールされ、バンドルには含まれません）、および API 仕様が記載されています。