Skip to content
Back to search

mcp-server

MCP server for interaction with Bitwarden.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/bitwarden/mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/bitwarden/mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bitwarden--mcp-server/badge.svg)](/listings/bitwarden--mcp-server)

HTML

<a href="/listings/bitwarden--mcp-server"><img src="/api/listings/bitwarden--mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

**For Vault Management and CLI tools:**

- [Bitwarden CLI](https://bitwarden.com/help/cli/) installed (ex. `npm install -g @bitwarden/cli`) - Node.js 22+ - Bitwarden account

**For Organization Administration:**

- Node.js 22+ - Bitwarden Teams or Enterprise organization - Organization owner or admin permissions

Configuration

> [!WARNING] > The configuration files below will contain sensitive credentials that grant access to your Bitwarden vault. Keep these files secure, never commit them to version control, and never share them with others. Ensure your MCP client (e.g., Claude Desktop) is configured to run the server locally only.

Option 1: Claude Desktop (Recommended)

Add to your Claude Desktop configuration file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

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

**Get your session token:**

bw login
bw unlock --raw

To enable organization administration features, add API credentials:

{
  "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"
      }
    }
  }
}

**Get organization API credentials:**

1. Go to your Bitwarden Web Vault 2. Navigate to your organization → Settings → My Organization 3. Scroll to "API Key" section 4. Click "View API Key" and authenticate

Option 2: Locally Built and Referenced

Requires that this repository be checked out locally. Once that's done:

npm install
npm run build

Then reference the built `dist/index.js` file from Claude desktop:

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

Option 3: Other MCP Clients

Any MCP-compatible client can connect to this server via stdio transport. Refer to your client's documentation for configuration details.

Environment Variables

| Variable | Required For | Description | Default | | ------------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | `BW_SESSION` | CLI operations | Session token from `bw unlock --raw` | - | | `BW_CLIENT_ID` | API operations | Organization API client ID | - | | `BW_CLIENT_SECRET` | API operations | Organization API client secret | - |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 356 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Bitwarden MCP Server
  2. A Model Context Protocol (MCP) server that provides AI assistants with secure access to Bitwarden password manager functionality through two complementary interfaces:
  3. - **Vault Management and CLI tools** via Bitwarden CLI
  4. - **Organization Administration** via Bitwarden Public API
  5. [![npm version](https://img.shields.io/npm/v/@bitwarden/mcp-server.svg)](https://www.npmjs.com/package/@bitwarden/mcp-server)
  6. > [!WARNING]
  7. > This MCP server is designed exclusively for local use and must never be hosted publicly or exposed over a network.
  8. >
  9. > When you grant an AI assistant access to this server, you are providing the ability to:
  10. >
  11. > - Read vault items including passwords, secure notes, and sensitive data
  12. > - Create, modify, and delete vault items
  13. > - Access organization secrets and administrative functions
  14. > - Expose credentials and vault contents through AI responses
  15. >
  16. > **You are responsible for:**
  17. >
  18. > - Ensuring this server runs only on your local machine or self-hosted environment
  19. > - Understanding what data you're exposing to your AI assistant
  20. > - Being aware that AI responses may inadvertently reveal sensitive information
  21. > - Using appropriate AI providers (consider self-hosted or local LLMs for sensitive data)
  22. > - Never sharing configuration files containing session tokens or API credentials
  23. > - Monitoring logs for unexpected activity
  24. >
  25. > **Never:**
  26. >
  27. > - Deploy this server to cloud hosting, containers, or public servers
  28. > - Share your MCP configuration files with others
  29. > - Use this server over untrusted networks
  30. > - Grant access to untrusted AI clients or services
  31. >
  32. > Use this tool responsibly and at your own risk.
  33. ## What is MCP?
  34. The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard that enables AI assistants to securely interact with local tools and services. This server exposes Bitwarden's vault management and organization administration capabilities to MCP-compatible AI clients like Claude Desktop.
  35. ## Features
  36. ### Vault Management and CLI tools (CLI)
  37. - **Session Management**: Unlock vault via native OS password dialog, lock vault, sync with server, check status
  38. - **Item Operations**: List, retrieve, create, edit, delete, restore vault items
  39. - Supports logins, secure notes, cards, and identities
  40. - Advanced filtering by URL, folder, collection, or trash status
  41. - **Folder Management**: Organize items with folders
  42. - **Attachments**: Upload, download, and manage file attachments
  43. - **Password Tools**: Generate secure passwords and retrieve TOTP codes
  44. - **Bitwarden Send**: Create and manage secure ephemeral shares (text/file)
  45. - **Organization Items**: Move items to organizations, manage collections
  46. - **Device Approval**: Approve or deny new device login requests
  47. - **Member Management**: Confirm organization member registrations
  48. ### Organization Administration (API)
  49. - **Collections**: Create, update, delete, and manage collection permissions
  50. - **Members**: Invite, update roles, remove members, manage group assignments
  51. - **Groups**: Create role-based access groups and assign members
  52. - **Policies**: Configure and enforce organization security policies
  53. - **Audit Logs**: Retrieve organization event history
  54. - **Subscriptions**: View and update organization billing information
  55. - **Bulk Import**: Import users and groups from external systems
  56. ## Quick Start
  57. ### Prerequisites
  58. **For Vault Management and CLI tools:**
  59. - [Bitwarden CLI](https://bitwarden.com/help/cli/) installed (ex. `npm install -g @bitwarden/cli`)
  60. - Node.js 22+
  61. - Bitwarden account
  62. **For Organization Administration:**
  63. - Node.js 22+
  64. - Bitwarden Teams or Enterprise organization
  65. - Organization owner or admin permissions
  66. ### Configuration
  67. > [!WARNING]
  68. > The configuration files below will contain sensitive credentials that grant access to your Bitwarden vault. Keep these files secure, never commit them to version control, and never share them with others. Ensure your MCP client (e.g., Claude Desktop) is configured to run the server locally only.
  69. #### Option 1: Claude Desktop (Recommended)
  70. Add to your Claude Desktop configuration file:
  71. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  72. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  73. ```json
  74. {
  75. "mcpServers": {
  76. "bitwarden": {
  77. "command": "npx",
  78. "args": ["-y", "@bitwarden/mcp-server"],
  79. "env": {
  80. "BW_SESSION": "your-session-token-here"
  81. }
  82. }
  83. }
  84. }
  85. ```
  86. **Get your session token:**
  87. ```bash
  88. bw login
  89. bw unlock --raw
  90. ```
  91. To enable organization administration features, add API credentials:
  92. ```json
  93. {
  94. "mcpServers": {
  95. "bitwarden": {
  96. "command": "npx",
  97. "args": ["-y", "@bitwarden/mcp-server"],
  98. "env": {
  99. "BW_SESSION": "your-session-token-here",
  100. "BW_CLIENT_ID": "organization.your-client-id",
  101. "BW_CLIENT_SECRET": "your-client-secret"
  102. }
  103. }
  104. }
  105. }
  106. ```
  107. **Get organization API credentials:**
  108. 1. Go to your Bitwarden Web Vault
  109. 2. Navigate to your organization → Settings → My Organization
  110. 3. Scroll to "API Key" section
  111. 4. Click "View API Key" and authenticate
  112. #### Option 2: Locally Built and Referenced
  113. Requires that this repository be checked out locally. Once that's done:
  114. ```bash
  115. npm install
  116. npm run build
  117. ```
  118. Then reference the built `dist/index.js` file from Claude desktop:
  119. ```json
  120. {
  121. "mcpServers": {
  122. "bitwarden": {
  123. "command": "node",
  124. "args": ["local/path/to/mcp-server/dist/index.js"],
  125. "env": {
  126. "BW_SESSION": "your-session-token-here"
  127. }
  128. }
  129. }
  130. }
  131. ```
  132. #### Option 3: Other MCP Clients
  133. Any MCP-compatible client can connect to this server via stdio transport. Refer to your client's documentation for configuration details.
  134. ### Environment Variables
  135. | Variable | Required For | Description | Default |
  136. | ------------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
  137. | `BW_SESSION` | CLI operations | Session token from `bw unlock --raw` | - |
  138. | `BW_CLIENT_ID` | API operations | Organization API client ID | - |
  139. | `BW_CLIENT_SECRET` | API operations | Organization API client secret | - |
  140. | `BW_API_BASE_URL` | API operations | Bitwarden API base URL | `https://api.bitwarden.com` |
  141. | `BW_IDENTITY_URL` | API operations | OAuth2 identity server URL | `https://identity.bitwarden.com` |
  142. | `BW_ALLOWED_DIRECTORIES` | File operations | Comma-separated list of allowed file directories. **Required** for file-based tools (e.g. `create_file_send`, `create_attachment`, `get` with `object: "attachment"`); when unset, all file operations are rejected. | - |
  143. | `BW_CLI_PATH` | CLI operations | Absolute path to the `bw` executable or its JS entry point. Only needed when the CLI cannot be auto-located on `PATH` (e.g. it is not on `PATH`, or a non-standard global install layout). | auto-resolved from `PATH` |
  144. **Note:** For self-hosted Bitwarden instances, set `BW_API_BASE_URL` and `BW_IDENTITY_URL` to your server URLs.
  145. **Note:** `BW_CLIENT_ID` and `BW_CLIENT_SECRET` are the environment variable names read by the MCP server. If you are using `bw login --apikey` in a startup script, the Bitwarden CLI reads `BW_CLIENTID` and `BW_CLIENTSECRET` (no underscores between words) for the same credentials. See the [Bitwarden CLI documentation](https://bitwarden.com/help/cli/#using-an-api-key).
  146. ## Usage Examples
  147. Once configured, you can interact with Bitwarden through your AI assistant:
  148. **Vault:**
  149. - "List all my login items"
  150. - "Get my credentials for github"
  151. - "Create a new secure note for my home WiFi information"
  152. - "Generate a 32-character password and save it for apple.com"
  153. - "Create a Send link for this file"
  154. **Organization Administration:**
  155. - "List all members in my organization"
  156. - "Invite user@example.com as an organization admin"
  157. - "Create a 'Development Team' collection"
  158. - "Show me the last 100 audit log events"
  159. - "What security policies are enabled?"
  160. ## Available Tools
  161. ### Vault Management and CLI Tools
  162. - **Session**: `lock`, `unlock`, `sync`, `status`
  163. - **Retrieval**: `list`, `get`
  164. - **Items**: `create_item`, `edit_item`, `delete`, `restore`
  165. - **Folders**: `create_folder`, `edit_folder`
  166. - **Attachments**: `create_attachment`
  167. - **Organizations**: `create_org_collection`, `edit_org_collection`, `edit_item_collections`, `move`, `confirm`
  168. - **Device Approval**: `device_approval_list`, `device_approval_approve`, `device_approval_approve_all`, `device_approval_deny`, `device_approval_deny_all`
  169. - **Send**: `create_text_send`, `create_file_send`, `list_send`, `get_send`, `edit_send`, `delete_send`, `remove_send_password`
  170. - **Utilities**: `generate`
  171. ### Organization Administration
  172. - **Collections**: `list_org_collections`, `get_org_collection`, `update_org_collection`, `delete_org_collection`
  173. - **Members**: `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`
  174. - **Groups**: `list_org_groups`, `get_org_group`, `create_org_group`, `update_org_group`, `delete_org_group`, `get_org_group_members`, `update_org_group_members`
  175. - **Policies**: `list_org_policies`, `get_org_policy`, `update_org_policy`
  176. - **Events**: `get_org_events`
  177. - **Subscriptions**: `get_org_subscription`, `update_org_subscription`
  178. - **Import**: `import_org_users_and_groups`
  179. ## Development
  180. ### Setup
  181. ```bash
  182. git clone https://github.com/bitwarden/mcp-server.git
  183. cd mcp-server
  184. npm install
  185. ```
  186. ### Commands
  187. ```bash
  188. npm run build # Compile TypeScript
  189. npm test # Run test suite
  190. npm run lint # Check code style
  191. npm run lint:fix # Auto-fix linting issues
  192. npm run inspect # Test with MCP Inspector
  193. ```
  194. ### Testing with MCP Inspector
  195. The MCP Inspector provides an interactive testing environment:
  196. ```bash
  197. npm run build
  198. npm run inspect
  199. ```
  200. This opens a web interface where you can:
  201. - Browse available tools
  202. - Test tool execution with custom inputs
  203. - View request/response payloads
  204. - Debug tool behavior
  205. ### Best Practices
  206. - Store credentials securely (use system keychains or environment managers)
  207. - Rotate session tokens regularly
  208. - Review audit logs periodically for suspicious activity
  209. - Never commit credentials to version control
  210. ### Testing
  211. The project includes Jest unit tests covering validation, CLI commands, and core functionality.
  212. ```bash
  213. # Run all tests
  214. npm test
  215. # Run tests in watch mode
  216. npm run test:watch
  217. # Run tests with coverage
  218. npm test -- --coverage
  219. # Run specific test file
  220. npm test validation.spec.ts
  221. # Run tests matching a pattern
  222. npm test -- --testNamePattern="validation"
  223. ```
  224. ### Debugging
  225. **Enable debug logging** by setting environment variables:
  226. ```bash
  227. export DEBUG=bitwarden:*
  228. export NODE_ENV=development
  229. ```
  230. ## Security Considerations
  231. - **Never commit** sensitive credentials (`BW_SESSION`, `BW_CLIENT_ID`, `BW_CLIENT_SECRET`)
  232. - **Use environment variables** for all sensitive configuration
  233. - **Validate all inputs** using Zod schemas (already implemented)
  234. - **Test with non-production data** when possible
  235. - **Monitor API usage** through your organization's audit logs
  236. - Understand the security and privacy impacts of exposing sensitive vault data to LLM and AI tools. Using a self-hosted or local LLM may be appropriate, for example.
  237. ## Troubleshooting
  238. ### CLI Issues
  239. - **Vault is locked**
  240. - Ask your AI assistant to run the `unlock` tool — the MCP server will open a native OS password dialog for you to enter your master password. The password is never sent through the MCP protocol or seen by the LLM.
  241. - On headless machines (no `DISPLAY` on Linux, no GUI session), the `unlock` tool will refuse to run. Use the manual fallback:
  242. ```bash
  243. bw unlock --raw
  244. # Copy the token and update BW_SESSION in your MCP config
  245. ```
  246. - **Session key is invalid**
  247. - Session tokens expire after inactivity
  248. - Ask your AI assistant to run the `unlock` tool to refresh the session in-place, or run `bw unlock --raw` manually and update your MCP configuration with the new token
  249. ### Unlocking the vault interactively
  250. The `unlock` tool lets your AI assistant prompt you for your master password without that password ever crossing the MCP channel.
  251. - The tool takes **no input parameters**. It cannot be invoked with a password argument.
  252. - When called, the server launches a **native OS password dialog**:
  253. - **macOS**: `osascript` secure input dialog
  254. - **Linux**: `zenity --password` (falls back to `kdialog --password`)
  255. - **Windows**: PowerShell WinForms password dialog (masked input)
  256. - The password is passed to `bw unlock --raw` via the `--passwordenv` flag with a randomized one-shot environment variable. It never appears in process arguments, in the MCP protocol, or in the LLM's context.
  257. - The LLM only ever sees `"Vault unlocked successfully."` or a sanitized failure message (e.g. `"Invalid master password."`, `"Unlock cancelled."`).
  258. - If you are in a non-interactive environment, the tool will refuse to run and return a fixed message directing you to the `bw unlock --raw` manual flow.
  259. ### API Issues
  260. - **Invalid client credentials**
  261. - Verify `BW_CLIENT_ID` starts with `organization.`
  262. - Ensure `BW_CLIENT_SECRET` is correct
  263. - Check that API keys haven't been rotated in the Admin Console
  264. - **403 Forbidden**
  265. - Verify you have organization owner or admin permissions
  266. - Some operations require specific roles (e.g., managing members)
  267. ## Contributing
  268. We welcome contributions! Please see [CONTRIBUTING.md](https://contributing.bitwarden.com/) for guidelines.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.