Bitwarden Public API and Secrets Manager (unofficial)

Bitwarden MCP 服务

非官方项目。 本项目并非由 Bitwarden Inc. 制作、关联或认可。 “Bitwarden”是 Bitwarden Inc. 的商标。请参阅 NOTICE。

一个本地模型上下文协议（stdio） 服务，将 Bitwarden 公共 API（组织管理）和 Bitwarden Secrets Manager（通过官方 SDK 管理项目和机密）作为有类型的读写工具开放出来。

适用场景：面向管理员的 MCP，让 AI 助手能够在单一主机上管理 成员、群组、集合、策略、许可证席位和 Secrets Manager 数据。专为自托管的 Bitwarden 实例、官方 Bitwarden Cloud 或两者同时使用而设计。

快速链接： 架构 · 贡献指南 · 安全策略 · 发布 · 更新日志 · 问题

维护状态

• 由一位维护者（@mguttmann）在业余时间尽力维护。 作者在生产环境中使用本项目。没有支持合同，也不保证响应时间。
• 安全修复优先于功能。请按照 SECURITY.md 中的说明私下报告 漏洞，切勿在公开问题中报告。
• 依赖更新由 Dependabot 提供；当运行时依赖存在已知安全公告时，CI 会失败。
• 仅最新的次要版本会获得修复。
• 欢迎提交问题和拉取请求；请参阅 CONTRIBUTING.md。

功能

• 公共 API： 成员、群组、集合、策略、事件、组织导入、订阅／许可。
• Secrets Manager： 通过官方 @bitwarden/sdk-napi 管理项目和机密 （零知识加密；以明文直接返回名称和值）。
• 支持双实例： 可连接自托管的 Bitwarden 实例、官方云服务或两者。工具在注册时即绑定到相应实例，因此不会意外路由错误。
• 手写工具涵盖常见工作流（bw_member_list、 bw_license_subscription_get、bws_secret_get_value 等），另有 bw_raw_request 作为应急入口。配置自托管实例和云服务后， 服务会列出 54 个工具，无论是否启用 Secrets Manager；工具名称和 必需参数由 tests/tool-contract.test.ts 固定，只会添加参数（可选），绝不删除或重命名。
• 发布包中不包含生成的工具： bw_<resource>_<op>_raw 工具的生成器已提供（npm run generate），但发布包中的规格文件（specs/public-api.spec.json）为空，因此不会注册生成工具。请参阅生成的原始工具。
• 写入操作需确认： 每个写入工具都会返回请求预览，除非调用时传入 confirm: "YES"。默认启用。模型会自行设置 confirm，因此这只是操作上的阻碍，并非安全边界（请参阅安全模型）。
• 设计上保护机密安全： 元数据列表绝不返回值；访问令牌仅在 Web 保管库中管理。
• 考虑令牌预算的列表默认值： 列表工具（bw_member_list、 bw_collection_list、bw_group_list、bw_event_query）默认返回精简投影，以控制在大模型工具调用的令牌预算内。有关选择完整嵌套响应的方式，请参阅列表响应结构。

这个 MCP 能做什么，不能做什么

Bitwarden 的 API 提供了不同的接口，各自有不同的身份验证和加密要求。这个 MCP 封装了所有能够 顺利 访问的功能。有些操作需要 Bitwarden 的加密层（因此我们使用官方 SDK）；另一些操作没有公开 API，只能通过 Web 保管库完成。

能做：Public 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/sdk-napi 交换，该 SDK 会处理 Bitwarden 的零知识加密。

• 列出、获取、创建、更新和删除项目（对已配置的 MA 可见）
• 列出机密元数据、获取包含明文值的完整机密，以及创建、 更新和删除机密

不能做：这些操作需要用户在 Web 保管库中完成

当前服务器使用的凭据（组织 API 密钥、机器帐户访问令牌）无法执行这些操作。SDK 和 bws CLI 也不支持这些操作。

• 创建、更新和删除 Machine Account
• 将项目分配给 Machine Account
• 创建或轮换 Machine Account Access Token
• 列出组织中的所有 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 地址筛选事件。

对于上述所有操作，请使用 Web 保管库：https://<your-host>/#/sm/{orgId}/。

要求

• Node.js 22.12 或更高版本（engines.node >=22.12；CI 使用 22、24 和 26 进行测试）。
• 至少一个实例（可自托管或云端）的 Bitwarden Public-API 密钥（client_id / client_secret）。
• 使用 Secrets Manager 时：Machine-Account 访问令牌（从 Web 保管库获取）。

平台支持

对于所有 公共 API 功能（成员、群组、集合、策略、事件、许可证调整），此 MCP 可在运行 Node.js 22.12 或更高版本的任何平台上使用。

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：

操作系统 / 架构	SDK 二进制文件	SM 工具
macOS Apple Silicon	可用	可用
macOS Intel	可用	可用
Linux x86_64（glibc）	可用	可用
Windows x86_64	可用	可用
Linux ARM64（Raspberry Pi、AWS Graviton）	不可用	存根
Linux Musl / Alpine	不可用	存根
其他	不可用	存根

在不受支持的平台上，MCP 仍会启动，所有公共 API 工具也能正常工作。bws_project_* 和 bws_secret_* 工具仍会注册，但调用时会返回“Secrets Manager SDK not available on this platform”；加载错误会在启动时以一条 warn 日志记录一次。

如果 Bitwarden 发布了包含新平台二进制文件的 SDK 版本，更新依赖和锁文件即可获取，无需更改代码。

安装

该软件包在 npm 上的名称为 the-real-bitwarden-mcp，通过 GitHub Actions 发布，并附带来源证明。其可执行文件为 bitwarden-mcp。所有安装方式的配置都相同（参见配置）。

本地 MCP 客户端（npx 或 npm install）

npx 会获取并启动软件包；请固定版本，以便由你决定是否更新，而不是让更新随着重启意外发生：

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

也可以一次性安装，然后启动可执行文件：

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

客户端配置请参见连接器接线。

网关和服务端（从 npm 安装固定版本）

使用锁文件安装固定版本，并通过 node 启动，无需使用 npx，也无需运行安装脚本。在空目录中执行一次：

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 根据操作系统和 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 工具会返回明确的“不可用”消息）。

生成原始工具

npm run refresh-spec 会将自托管实例的 Swagger 文档拉取到 specs/public-api.spec.json，而 npm run generate 会根据该文档为每项操作生成一个 bw_<resource>_<op>_raw 工具。随附的规范为空（{"paths": {}}），因此正常构建时不会注册任何生成的工具。生成工具会改变工具列表；如果服务运行在固定工具集合的网关后，请将此操作视为部署变更。

配置

所有值均为环境变量。它们来自进程环境（例如 node --env-file=.env，或 MCP 客户端配置中的 env 块）。如果启动服务时未使用 --env-file（或 --env-file-if-exists），也会读取进程工作目录中的 .env 文件，并且只填充尚未设置的变量；使用 --env-file 时则会忽略该文件。 至少必须有一个实例完成全部配置，否则服务会拒绝启动。实例只配置了部分变量（四个变量中有些已配置、有些未配置）也会导致启动失败；API 基础 URL 或身份验证 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 工具（可选）	默认使用自托管身份验证 URL
BWS_ORG_ID	SM 项目/密钥工具	组织 UUID，在未传入 organizationId 时使用
BITWARDEN_CONFIRM_WRITES		默认 true：写入工具返回预览，除非 confirm: "YES"
BITWARDEN_READ_ONLY		默认 false；true：写入工具仍会列出，但拒绝运行
LOG_LEVEL		debug | info | warn（默认）| error
HTTP_TIMEOUT_MS		默认 30000；用于 API 和 OAuth 令牌请求；每次 bws_* 调用使用一个截止时间
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_*	结果
存在	不存在	注册公共 API 操作工具和 SM 工具。不会注册许可证工具。bw_raw_request(instance:"cloud") 会拒绝请求。
不存在	存在	仅可使用许可证工具和原始云端请求。
存在	存在	注册所有工具组。
不存在	不存在	服务无法启动。

获取 Secrets Manager 访问令牌

1. 在自托管保险库中，打开 Secrets Manager > Machine accounts，并 创建一个机器账户（使用 mcp-bitwarden 这样的中性名称即可）。
2. 授予该机器账户对你希望 MCP 管理的项目的访问权限。
3. 为该机器账户创建一个访问令牌，并将明文值复制到 .env 中作为 BWS_ACCESS_TOKEN。
4. 同时将 BWS_ORG_ID 设置为组织 UUID（可从 Web 保险库中组织的 URL 获取）。
5. 重启 MCP；此时 bws_* 工具即可使用。

在此之前，SM 工具会保持注册状态，但会返回 "Secrets Manager not configured"，以便用户仍能发现这些工具。

BWS_ACCESS_TOKEN 格式

访问令牌由三部分组成，以 . 和 : 分隔：

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 用于解密负载。绝不会发送到服务器。

向身份服务器发送的 OAuth 请求使用 scope=api.secrets（而非 api.organization）。组织公共 API 密钥（使用 organization.* client_id 和 api.organization scope）无法访问 Secrets Manager 端点；这是有意为之，并非错误。

自托管 Bitwarden：Secrets Manager 的可用性

当前的自托管 Bitwarden（服务器 2026.x）将 Secrets Manager API 包含在标准的 bitwarden-api 容器中；不存在独立的 sm-api 容器，bwdata/config.yml 中也没有 enable_secrets_manager 开关。如果你的 docker-compose.yml 中没有显示 sm-api 服务，这是正确且符合预期的。

在 Web 保险库中创建具有有效访问令牌的机器账户后，即可访问 SM 端点。

列表响应结构

四个列表工具（bw_member_list、bw_collection_list、 bw_group_list、bw_event_query）默认返回精简投影，因为 Bitwarden 的 Public API 会在每个列表项中嵌入完整的权限图，导致响应膨胀数倍，并在组织规模适中时超出大模型工具调用的 token 预算。

默认字段：

工具	默认字段
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）。根节点为列表的结果会转换为对象：保留的项移至 items，与 responseTruncated 并列。被截断的列表旁若有 continuationToken，则会将其移除（continuationTokenRemoved: true），因为它会从被截掉的项之后继续读取。不含列表的输出（例如预览）会整体替换为 responseTruncated 对象。此处不会截断错误结果；上游错误文本会另外缩短。
• 输入大小。 如果参数中的任意字符串超过 102400 字节（100 KiB），或任意数组包含超过 10000 项（例如 bw_org_import 包含超过 10000 个成员或组），则工具调用会在发送任何内容之前被拒绝。错误会指出参数路径和大小，但不会显示参数值。
• 令牌退避。 某个客户端（自托管、云端、Secrets Manager REST 和 Secrets Manager SDK 登录）的令牌请求连续失败 3 次后，新的令牌请求会暂停 30 s。暂停期间的调用会立即失败，并显示 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 注册服务（用户级或项目级），或将相同的 mcpServers 配置块添加到项目根目录的 .mcp.json 文件中：

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

网关和无头使用

服务仅通过 stdio 使用 MCP 通信，不需要终端。网关或 supervisor 会安装固定版本的 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

• 日志以 JSON 行的形式写入 stderr（pino，级别为 LOG_LEVEL）；stdout 仅承载 MCP 流。
• **协议修订版本：**使用 2025-06-18 或 2025-11-25 版本进行 initialize 的客户端会获得对应修订版本；使用 2026-07-28 版本（server/discover）进行初始化的客户端会获得 2026-07-28 版本。由 tests/protocol-versions.test.ts 固定。
• **消息大小限制：**MCP SDK 的 stdio 传输最多接受 10 MiB 的传入 行（每行一条 JSON-RPC 消息）。超过此大小的行会关闭传输；服务会记录一行 error 日志并以代码 1 退出，客户端必须重新启动服务。
• **工具名称稳定不变。**工具名称、参数名称和必需参数不会改变，也不会移除任何工具或参数；工具 可以新增可选参数。调用方可察觉的变更会列在 变更日志的“行为变更”部分。 scripts/container-smoke.sh 会按照网关的方式构建并探测服务（参见 CONTRIBUTING）。
• **不隔离用户：**每个调用方都拥有配置密钥的全部权限。请在 网关中限制各用户可调用的工具（参见SECURITY.md）。

工具参考

在 MCP 内运行 bw_help，即可获取按类别分组且始终保持最新的目录。 简要列表：

公共 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 （最后两项始终返回错误，参见“无法”）
• 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 会随保存请求一起传递（例如 policy type 5 的 defaultUserCollectionName）；不会与策略一同存储。
• bw_event_query：continuationToken 用于继续获取被截断的结果；传入 返回的令牌，并使用相同的 start、end、筛选条件和 limit。limit 最多返回指定数量的事件（必须是至少为 1 的整数， 上限为 PAGINATION_MAX_ITEMS）；存在更多事件时，结果为 truncated: true 并包含 continuationToken，即使停止位置 位于 API 页面中间也是如此。 bw_member_list、bw_group_list 和 bw_collection_list 不接受 令牌：公共 API 会在一个响应中返回这些列表。
• truncated: true 表示 API 仍提供下一页，但服务已在达到 PAGINATION_MAX_ITEMS 或 PAGINATION_MAX_PAGES 时停止。如果 最后一页恰好在达到限制时结束，下一页可能为空：API 会发送令牌，但不会说明后面是否还有更多项目， 而服务不会额外发送请求来确认。此时使用返回的令牌继续请求会得到空列表。

Public API：生成的原始工具（自托管）

已发布的包中不包含任何工具（规范为空，见 生成的原始工具）。 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）

这四种工具都接受一个增量值，将当前值与增量相加后作为新的绝对总量，通过 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。如果省略 note 或 projectIds，bws_secret_update 会保留当前备注和项目（它会先读取密钥）；传入这些参数即可更改相应内容。机器账户无法移除密钥的所有项目：如果密钥属于某个项目，服务端会拒绝使用 projectIds: [] 进行更新。

SDK 不会在启动时登录，而是在首次调用 bws_* 工具时使用 BWS_ACCESS_TOKEN 登录。一个 HTTP_TIMEOUT_MS 截止时间适用于整个 bws_* 调用，包括登录，以及调用 bws_secret_update 时因缺少 note 或 projectIds 而读取当前密钥的操作。超时后仍在进行的登录会继续运行；下次调用会等待该登录完成，而不是另行启动一次登录。写入操作超时后，无法确定是否已生效。

Secrets Manager：仅限 Web Vault（始终为存根）

• 机器账户：bws_machine_account_list、..._get、..._create、 ..._update、..._delete、..._projects、..._grant_project、 ..._revoke_project
• 访问令牌：bws_access_token_list、..._create、..._revoke

这些工具不适用于本服务使用的凭据；只有登录 Web Vault 的用户才能管理机器账户和访问令牌。可通过 tools/list 和 bw_help 查看这些工具，但调用时始终会返回带有 Web Vault 链接的 isError: true。请使用 https://<your-host>/#/sm/{orgId}/machine-accounts 进行管理。

通用

• bw_raw_request：提供 instance 参数（selfhost、cloud 或 sm）的备用入口。 对于手写工具未涵盖的任何 Public API 或 SM REST 调用，都可以使用此工具。 注意：SM bws_* CRUD 操作通过 SDK 执行（而非原始 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。若调用者不得执行这些操作，请使用只读模式或网关规则。
• 服务会发送 MCP 指令，告知模型应将 Bitwarden 数据视为数据，绝不可视为指令。这只是对模型的提示，并非控制措施。
• bws_secret_list 工具只返回密钥标识符（不含值字段）。明文值仅通过 bws_secret_get_value(id) 一次返回一个密钥：bws_secret_create / bws_secret_update 返回不含值的元数据，确认门控预览则会将密钥值显示为 <redacted, N chars>。
• 返回给客户端的日志和错误文本都会经过同一个清理器（src/redact.ts）：其中列出的键（Bearer 令牌、客户端密钥、访问令牌、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 段（第二个 . 与 : 之间的内容）。不要将完整原始令牌或加密密钥用作这两个字段。

最快的诊断方法：在身份验证失败后，立即在服务主机上运行 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）。

登录失败（令牌错误、身份服务器无法访问）会返回不同的工具错误：“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 规范。