# @bitwarden/mcp-server 中文文档

规范地址：https://npmcn.com/package/%40bitwarden/mcp-server/

版本：2026\.7\.0
npm 元数据更新时间：2026-07-07T17:49:12.509Z
中文译文更新时间：2026-11-08T04:52:57.875Z
软件包许可：SEE LICENSE IN LICENSE\.txt

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bitwarden/mcp-server
原文对照：https://npmcn.com/package/%40bitwarden/mcp-server/?lang=original
项目主页：https://bitwarden.com/
源码仓库：https://github.com/bitwarden/mcp-server

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：440 kB，71 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：3 个
- 首次发布：2025-07-09T21:27:34.538Z
- 最新版本发布：2026-07-07T17:49:12.260Z
- 近 30 天下载量：9434（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 5 个）

## 中文简介

Bitwarden MCP 服务器

## 安装

```sh
npm install @bitwarden/mcp-server
```

也可以使用：`pnpm add @bitwarden/mcp-server`、`yarn add @bitwarden/mcp-server`、`bun add @bitwarden/mcp-server`

## README

# Bitwarden MCP 服务器

一个模式上下文协议(MCP)服务器,通过两个互补接口为AI助手提供安全访问Bitwarden密码管理器功能:

-   **故障管理和CLI工具** 通过 Bitwarden CLI
-   **组织行政** 通过 Bitwarden 公共 API

[![npm version](https://img.shields.io/npm/v/@bitwarden/mcp-server.svg)](https://www.npmjs.com/package/@bitwarden/mcp-server)

> \[尖叫声\] 这个MCP服务器是专为本地用途而设计的,绝不能通过网络公开或曝光.
> 
> 当您允许AI助手访问此服务器时, 您正在提供以下能力:
> 
> -   读取包括密码、安全笔记和敏感数据在内的金库项目
> -   创建、修改和删除金库项目
> -   查阅组织机密和行政职能
> -   通过大赦国际的答复公布证书和金库内容
> 
> **您负责:**
> 
> -   确保此服务器只运行在您的本地机上或自托管环境中
> -   了解你向人工智能助理透露的数据
> -   意识到大赦国际的答复可能无意中透露出敏感信息
> -   使用适当的人工智能供应商(考虑自我托管或本地有限责任公司提供敏感数据)
> -   永不共享包含会话符号或 API 证书的配置文件
> -   监测意外活动的日志
> 
> **永远:**
> 
> -   将此服务器用于云托管、容器或公共服务器
> -   与其他人共享您的 MCP 配置文件
> -   使用此服务器覆盖未信任的网络
> -   允许无信任的AI客户或服务访问
> 
> 使用这个工具是负责任的 并冒着自己的风险.

## 什么是MCP吗?

这个 [示范背景协议](https://modelcontextprotocol.io/) 是一种开放标准,使AI助手能够安全地与本地工具和服务互动. 这个服务器将Bitwarden的金库管理和组织管理能力暴露给克洛德桌面等MCP相容的AI客户端.

## 特征

### 地窖管理和CLI工具(CLI)

-   **会话管理**: 通过本地 OS 密码对话框解锁金库, 锁定金库, 与服务器同步, 检查状态
-   **项目业务**: 列出、检索、创建、编辑、删除、恢复金库项目
    -   支持登录、安全笔记、卡片和身份
    -   通过 URL、文件夹、收藏或垃圾状态进行高级过滤
-   **文件夹管理**: 组织带有文件夹的项目
-   **附录**: 上传、下载和管理文件附件
-   **密码工具**: 生成安全密码并获取 TOTP 代码
-   **Bitwarden 发送**: 创建和管理安全电子股票(文本/文件)
-   **组织项目**: 将项目移动到组织,管理收藏
-   **设备批准**: 批准或拒绝新设备登录请求
-   **成员管理层**: 确认组织成员注册

### 组织行政管理

-   **收款**: 创建、更新、删除和管理收藏权限
-   **成员**: 邀请、更新角色、删除成员、管理组任务
-   **组**: 创建基于角色的接入组并指派成员
-   **政策**: 制定和执行组织安全政策
-   **审计日志**: 检索组织活动历史
-   **订阅**: 查看和更新组织账单信息
-   **批量导入**:从外部系统导入用户和组

## 快速启动

### 先决条件

**对于地壳管理和CLI工具:**

-   [Bitwarden 语录](https://bitwarden.com/help/cli/) 已安装( 前). `npm install -g @bitwarden/cli`(中文(简体) )
-   节点.js 22+
-   比特沃德账户

**关于组织行政:**

-   节点.js 22+
-   Bitwarden 团队或企业组织
-   组织所有者或管理员权限

### 配置

> \[尖叫声\] 下面的配置文件将包含允许访问您 Bitwarden 金库的敏感证书 。 保持这些文件的安全,从不将这些文件用于版本控制,也从不与他人共享. 确保您的 MCP 客户端( 如 Claude Desktop ) 配置为仅本地运行服务器 .

#### 备选案文1:克洛德桌面(建议)

添加到您的 Claude 桌面配置文件 :

-   **马科斯**数字 : `~/Library/Application Support/Claude/claude_desktop_config.json`
-   **窗口**数字 : `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "bitwarden": {
      "command": "npx",
      "args": ["-y", "@bitwarden/mcp-server"],
      "env": {
        "BW_SESSION": "your-session-token-here"
      }
    }
  }
}
```

**获取会话符号 :**

```bash
bw login
bw unlock --raw
```

为了具备组织管理特点,增加API证书:

```json
{
  "mcpServers": {
    "bitwarden": {
      "command": "npx",
      "args": ["-y", "@bitwarden/mcp-server"],
      "env": {
        "BW_SESSION": "your-session-token-here",
        "BW_CLIENT_ID": "organization.your-client-id",
        "BW_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

**获取组织 API 证书 :**

1.  转到您的 Bitwarden 网页默认
2.  导航到您的组织 设置 我的组织
3.  滚动到“ API 密钥” 部分
4.  点击“ 查看 API 密钥” 并认证

#### 备选案文2:当地建造和参考

要求本地检查此仓库 。 完成后:

```bash
npm install
npm run build
```

然后参考已建成的 `dist/index.js` 来自 Claude 桌面的文件 :

```json
{
  "mcpServers": {
    "bitwarden": {
      "command": "node",
      "args": ["local/path/to/mcp-server/dist/index.js"],
      "env": {
        "BW_SESSION": "your-session-token-here"
      }
    }
  }
}
```

#### 备选办法3:其他多边方案客户

任何MCP兼容客户端都可以通过stdio传输连接到这个服务器. 请查看您的客户端的文档以了解配置细节 .

### 环境变量

| 变量 | 所需时间 | 说明 | 默认 |
| --- | --- | --- | --- |
| `BW_SESSION` | CLI行动 | 会话符号来自 `bw unlock --raw` | \- 说吧 |
| `BW_CLIENT_ID` | API 操作 | 组织 API 客户端标识 | \- 说吧 |
| `BW_CLIENT_SECRET` | API 操作 | 组织 API 客户端秘密 | \- 说吧 |
| `BW_API_BASE_URL` | API 操作 | Bitwarden API 基础 URL | `https://api.bitwarden.com` |
| `BW_IDENTITY_URL` | API 操作 | OAuth2 身份服务器 URL | `https://identity.bitwarden.com` |
| `BW_ALLOWED_DIRECTORIES` | 文件操作 | 逗号分隔的允许文件目录列表 . **需求** 用于基于文件的工具(例如:. `create_file_send`, (中文(简体) ), `create_attachment`; 未设置时, 所有文件操作都会被拒绝 . | \- 说吧 |
| `BW_CLI_PATH` | CLI行动 | 绝对路径 `bw` 可执行性或其JS切入点. 只有当 CLI 无法自动定位时才需要 `PATH` (例如,它没有在 `PATH`,或非标准的全球安装布局). | 自动解析自 `PATH` |

**说明:** 对于自备的 Bitwarden 实例, 设置 `BW_API_BASE_URL` 财务报告和审定财务报表 `BW_IDENTITY_URL` 到您的服务器 URL.

**说明:** `BW_CLIENT_ID` 财务报告和审定财务报表 `BW_CLIENT_SECRET` 是 MCP 服务器读取的环境变量名称。 使用时 `bw login --apikey` 在启动脚本中, Bitwarden CLI 读取 `BW_CLIENTID` 财务报告和审定财务报表 `BW_CLIENTSECRET` (无下划线) 见 [Bitwarden CLI 文档](https://bitwarden.com/help/cli/#using-an-api-key)。 。 。 .

## 用法实例

配置后, 您可以通过您的 AI 助手与 Bitwarden 交互 :

**默认 :**

-   "记录我所有的登录项目"
-   "给我的证书"
-   "为我的家WiFi信息创建新的安全字条"
-   "Generating a 32-Charracter 密码并保存为苹果.com"
-   创建此文件的发送链接

**组织行政:**

-   组织成员名单
-   "邀请 [用户@ example.com](mailto:user@example.com) 作为组织的管理机构
-   "创建"开发团队"集"
-   "给我看看最后的100个审计记录"
-   "什么安全政策是允许的?"

## 可用工具

### 默认管理和 CLI 工具

-   **会议**数字 : `lock`, (中文(简体) ), `unlock`, (中文(简体) ), `sync`, (中文(简体) ), `status`
-   **检索**数字 : `list`, (中文(简体) ), `get`
-   **项目**数字 : `create_item`, (中文(简体) ), `edit_item`, (中文(简体) ), `delete`, (中文(简体) ), `restore`
-   **文件夹**数字 : `create_folder`, (中文(简体) ), `edit_folder`
-   **附录**数字 : `create_attachment`
-   **组织**数字 : `create_org_collection`, (中文(简体) ), `edit_org_collection`, (中文(简体) ), `edit_item_collections`, (中文(简体) ), `move`, (中文(简体) ), `confirm`
-   **设备批准**数字 : `device_approval_list`, (中文(简体) ), `device_approval_approve`, (中文(简体) ), `device_approval_approve_all`, (中文(简体) ), `device_approval_deny`, (中文(简体) ), `device_approval_deny_all`
-   **发送**数字 : `create_text_send`, (中文(简体) ), `create_file_send`, (中文(简体) ), `list_send`, (中文(简体) ), `get_send`, (中文(简体) ), `edit_send`, (中文(简体) ), `delete_send`, (中文(简体) ), `remove_send_password`
-   **公用事业**数字 : `generate`

### 组织行政

-   **收款**数字 : `list_org_collections`, (中文(简体) ), `get_org_collection`, (中文(简体) ), `update_org_collection`, (中文(简体) ), `delete_org_collection`
-   **成员**数字 : `list_org_members`, (中文(简体) ), `get_org_member`, (中文(简体) ), `invite_org_member`, (中文(简体) ), `update_org_member`, (中文(简体) ), `remove_org_member`, (中文(简体) ), `reinvite_org_member`, (中文(简体) ), `get_org_member_groups`, (中文(简体) ), `update_org_member_groups`
-   **组**数字 : `list_org_groups`, (中文(简体) ), `get_org_group`, (中文(简体) ), `create_org_group`, (中文(简体) ), `update_org_group`, (中文(简体) ), `delete_org_group`, (中文(简体) ), `get_org_group_members`, (中文(简体) ), `update_org_group_members`
-   **政策**数字 : `list_org_policies`, (中文(简体) ), `get_org_policy`, (中文(简体) ), `update_org_policy`
-   **活动**数字 : `get_org_events`
-   **订阅**数字 : `get_org_subscription`, (中文(简体) ), `update_org_subscription`
-   **导入**数字 : `import_org_users_and_groups`

## 发展

### 设置

```bash
git clone https://github.com/bitwarden/mcp-server.git
cd mcp-server
npm install
```

### 图标

```bash
npm run build        # Compile TypeScript
npm test             # Run test suite
npm run lint         # Check code style
npm run lint:fix     # Auto-fix linting issues
npm run inspect      # Test with MCP Inspector
```

### 与 MCP 检查员进行测试

MCP检查员提供了一个交互式测试环境:

```bash
npm run build
npm run inspect
```

这将打开一个网络界面, 您可以在其中:

-   浏览可用的工具
-   使用自定义输入的测试工具执行
-   查看请求/答复有效载荷
-   调试工具行为

### 最佳做法

-   安全存储证书(使用系统键链或环境管理员)
-   定期旋转会话符号
-   定期审查可疑活动的审计记录
-   从不将证书承诺给版本控制

### 测试

该项目包括Jest单元测试,涵盖验证,CLI命令,以及核心功能.

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm test -- --coverage

# Run specific test file
npm test validation.spec.ts

# Run tests matching a pattern
npm test -- --testNamePattern="validation"
```

### 调试

**启用调试日志** 设置环境变量:

```bash
export DEBUG=bitwarden:*
export NODE_ENV=development
```

## 安全考虑

-   **永远不要承诺** 敏感全权证书`BW_SESSION`, (中文(简体) ), `BW_CLIENT_ID`, (中文(简体) ), `BW_CLIENT_SECRET`(中文(简体) )
-   **使用环境变量** 用于所有敏感配置
-   **验证所有输入** 使用 Zod 计划( 已经执行)
-   **用非生产数据进行测试** 可能时
-   **监视 API 使用情况** 通过您的组织的审计日志
-   了解敏感金库数据被LLM和AI工具曝光对安全和隐私的影响. 例如,使用自我托管的或当地LLM可能是适当的.

## 解决问题

### CLI 问题

-   **默认已锁定**
    
    -   叫你的人工智能助理来操作 `unlock` 工具 —— MCP 服务器将打开本地的 OS 密码对话框供您输入主密码 。 密码从未通过MCP协议或LLM看到.
        
    -   无头机器(无) `DISPLAY` 在 Linux 上,没有图形界面会话) `unlock` 工具将拒绝运行。 使用手动倒计时 :
        
        ```bash
        bw unlock --raw
        # Copy the token and update BW_SESSION in your MCP config
        ```
        
-   **会话密钥无效**
    
    -   不活动后会话符号过期
    -   叫你的人工智能助理来操作 `unlock` 用于在位置上刷新会话或运行的工具 `bw unlock --raw` 手动更新您的 MCP 配置, 并使用新令牌

### 交互式解锁金库

这个 `unlock` 工具让您的 AI 助手提示您使用主密码, 而不会通过 MCP 频道.

-   这个工具需要 **无输入参数**。不能用密码参数引用它.
-   当呼叫时,服务器会发射一个 **本地 OS 密码对话框**数字 :
    -   **马科斯**数字 : `osascript` 安全输入对话框
    -   **链接**数字 : `zenity --password` (倒计时) `kdialog --password`(中文(简体) )
    -   **窗口**: PowerShell WinForms 密码对话框( 大量输入)
-   密码传到 `bw unlock --raw` 通过 `--passwordenv` 带有随机一发环境变量的旗帜。 它从未出现在进程论证,MCP协议,或LLM的背景中.
-   LLM只见过 `"Vault unlocked successfully."` 或已消毒的故障信息(例如:. `"Invalid master password."`, (中文(简体) ), `"Unlock cancelled."`) (中文(简体) ).
-   如果您处于非交互环境, 工具将拒绝运行, 并返回指示您到 `bw unlock --raw` 手动流动.

### API 问题

-   **无效的客户端证书**
    
    -   校验 `BW_CLIENT_ID` 开始于 `organization.`
    -   保证 `BW_CLIENT_SECRET` 正确的
    -   请检查API 密钥是否已在管理控制台旋转
-   **403 禁止使用**
    
    -   校验您的组织拥有者或管理员权限
    -   一些业务需要发挥具体作用(如管理成员)

## 捐款

我们欢迎捐款! 请看 [捐款额](https://contributing.bitwarden.com/) 准则.

## 常见问题

### @bitwarden/mcp-server 是什么？

Bitwarden MCP 服务器

### 如何安装 @bitwarden/mcp-server？

在项目目录运行 npm install @bitwarden/mcp-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp-server-bitwarden，可以用 npx mcp-server-bitwarden 直接运行。

### @bitwarden/mcp-server 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bitwarden\_\_mcp-server 是否存在。

### @bitwarden/mcp-server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bitwarden/mcp-server 可以商用吗？

@bitwarden/mcp-server 使用 SEE LICENSE IN LICENSE\.txt 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @bitwarden/mcp-server 的下载量有多少？

根据 npm 官方下载统计，@bitwarden/mcp-server 在 2026/10/08 – 2026/11/06 这 30 天内被下载 9,434 次，日均约 314 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bitwarden/mcp-server 还在维护吗？

最新版本 2026\.7\.0 发布于 2026/07/08（4 个月前）；至今共发布 18 个版本，其中过去 12 个月发布了 5 个；首次发布于 2025/07/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。