Vaultwarden-MCP

Vaultwarden MCP: connect Claude to your self-hosted password vault

An MCP server that gives Claude access to a self-hosted Vaultwarden or Bitwarden vault through the official Bitwarden CLI. Search your logins, look them up, add new ones, and edit them, from a chat window.

Claude never receives a password. It cannot change anything without you clicking Save.

Not affiliated with Bitwarden or Vaultwarden. This is a personal project that drives the published Bitwarden CLI. Read SECURITY.md before pointing it at a vault you care about.

Contents · What it does · Install · Compatibility · Settings · Tools · Troubleshooting · Security

What it does

Ask for a login and a card appears beside the reply, password hidden behind a row of dots with a copy button next to it. Ask for a new one and you get a filled-in draft with a generated password that saves when you press Save, and not before.

Claude can	Claude cannot
Search the vault and list folders	Read a password, one-time code, or note, unless you approve it in a desktop window, once per request
See item names, usernames, and sites	Create, edit, or trash anything until you press Save or Confirm in the card
See whether an item has a password, code, or notes	Delete permanently. Deletes go to the trash, where your server keeps them 30 days
Generate a password into the card	Change which vault server is used. That is fixed at install time
Prepare changes for you to confirm	See your master password. You type it into a desktop window

SECURITY.md explains why each line is drawn where it is.

The card

Anything sensitive happens here rather than in the conversation. The card follows Claude's light and dark themes.

Reveal shows a secret for thirty seconds, then hides it. Copy never displays it at all: the server writes the value straight to your clipboard and clears it thirty seconds later, tagged so Windows clipboard history and cloud clipboard skip it. Items you flagged "master password re-prompt" ask for your password again before either.

Site icons come from your own instance's icon service, the same one the web vault uses. That is the only origin the card may load anything from. Items without an icon show their initial instead.

Install

Claude Desktop, from a release

1. Download vaultwarden-mcp-<version>.mcpb from the latest release.
2. Double-click it. Claude Desktop installs it as an extension.
3. Enter your vault address, such as https://vault.example.com. Everything else is optional.
4. Ask Claude to sign in to your vault. A window opens on your desktop for your email, master password, and two-step code if you use one.

Nothing else to install. The Bitwarden CLI travels inside the bundle.

Claude Desktop, from source

git clone https://github.com/ShadowsDistant/Vaultwarden-MCP.git
cd Vaultwarden-MCP
npm install --legacy-peer-deps
npm run build
node scripts/install.mjs --server https://vault.example.com --email you@example.com

Then quit Claude Desktop completely and reopen it.

On Windows, use scripts\setup.ps1 instead. It builds into %USERPROFILE%\.vaultwarden-mcp, which matters if you cloned into a OneDrive folder:

.\scripts\setup.ps1 -Install -Server https://vault.example.com -Email you@example.com

Claude Code

claude mcp add vaultwarden --env VW_MCP_SERVER_URL=https://vault.example.com -- node /path/to/Vaultwarden-MCP/dist/index.js

Any other MCP client

The server speaks MCP over stdio, so anything that can launch a stdio server can run it. Point your client's config at the built entry point:

{
  "mcpServers": {
    "vaultwarden": {
      "command": "node",
      "args": ["/path/to/Vaultwarden-MCP/dist/index.js"],
      "env": {
        "VW_MCP_SERVER_URL": "https://vault.example.com",
        "VW_MCP_EMAIL": "you@example.com"
      }
    }
  }
}

On Windows, give the full path to node.exe and escape the backslashes in the paths.

Signing in

Ask Claude to sign in. The window that opens belongs to this server, not to Claude, and what you type goes down a pipe to the Bitwarden CLI without passing through the conversation.

If anything ever asks for your master password inside the chat, it is not this server.

Compatibility

Node	20 or newer. The Bitwarden CLI is bundled.
Vault	Vaultwarden 1.37.2 or newer, or Bitwarden's hosted service.
Windows	Full support. Sign-in and confirmation windows use WPF.
macOS	Full support, using osascript for windows.
Linux	Needs zenity or kdialog for the windows. Without one, unlock the vault yourself and pass BW_SESSION.
Inline cards	Need a host implementing the MCP Apps extension. Claude Desktop and Claude Code do.
Other MCP clients	The tools work anywhere. Without card support the card-only tools are never registered, and reveals and confirmations fall back to desktop windows.

A headless machine can still run the server: unlock the vault yourself with bw unlock --raw and start it with BW_SESSION set.

Settings

Set these in the extension's settings in Claude Desktop, or as environment variables in your client's config.

Variable	Default	What it does
VW_MCP_SERVER_URL	required	Your vault address. Deliberately not settable from a conversation.
VW_MCP_EMAIL	none	Pre-fills the sign-in window.
VW_MCP_IDLE_LOCK_MIN	0	Also lock after this many idle minutes. 0 locks only when the app closes.
VW_MCP_MODEL_REVEAL	ask	ask lets Claude request one secret at a time, with a window you must approve. off refuses outright.
VW_MCP_HOME	~/.vaultwarden-mcp	Where the vault cache, config, and log live.
VW_MCP_CA_FILE	none	A CA bundle, if your instance uses a private certificate authority.
VW_MCP_ALLOW_HTTP	unset	Permit a plain-http address for a host other than localhost.
VW_MCP_REVEAL_SECONDS	30	How long a revealed secret stays on screen.
VW_MCP_CLIPBOARD_CLEAR_SECONDS	30	How long a copied secret stays on the clipboard.
BW_SESSION	unset	An already-unlocked session, for a machine with no desktop.

Tools

⧉ marks the tools that draw a card.

Tool	What it does
vault_status ⧉	Whether the vault is signed in, locked, or unlocked, and which instance it uses
vault_login ⧉	Sign in, in a window on your desktop
vault_unlock ⧉	Unlock, in a window on your desktop, then show the vault
vault_lock	Lock immediately and forget the session key
vault_sync	Pull the latest contents from the server
vault_search ⧉	Find items by name, site, or folder. Names and hosts only, no usernames in bulk
vault_get_item ⧉	One item in full, minus every secret
vault_list_folders	The folders, with the ids used to file or filter
vault_generate_password ⧉	Generate a password or passphrase into the card, not the conversation
vault_create_login ⧉	Prepare a new login for you to save
vault_edit_item ⧉	Prepare a change for you to confirm, shown as a before-and-after
vault_trash_item ⧉	Prepare to move an item to the trash, for you to confirm
vault_restore_item ⧉	Bring an item back out of the trash
vault_reveal_secret	Ask you, in a desktop window, to release one secret into the conversation

A second set of tools serves the card alone: reading a secret on a click, copying to the clipboard, saving a draft. They are marked app-only and stay unregistered unless the client declares MCP Apps support at startup, so on any other host they do not exist and nothing can call them.

Troubleshooting

"The Bitwarden CLI is not installed." The bundled CLI did not survive the install. Re-run npm install --legacy-peer-deps and npm run build, or reinstall the extension.

No window appears when signing in. On Linux, install zenity or kdialog. Elsewhere, check ~/.vaultwarden-mcp/logs/server.log. As a fallback, run bw unlock --raw yourself and pass the result as BW_SESSION.

"Could not reach the vault server." Check the address in your settings and that the instance is up. For a private certificate authority, point VW_MCP_CA_FILE at the bundle.

Claude says an item was created but it is not there. It was a draft, and drafts are not written until you press Save. If no card appeared at all, your host does not support MCP Apps.

The vault keeps locking. By default it stays open until the app closes. If you set VW_MCP_IDLE_LOCK_MIN, raise it or set it back to 0.

Development

npm install --legacy-peer-deps
npm run build     # tsc, then bundle the card into a single HTML file
npm test          # 81 tests against a fake Bitwarden CLI, over real stdio
npm run preview   # card views at http://localhost:8766, plus /selftest.html
npm run pack      # build the .mcpb extension bundle

No test touches a real vault. test/fake-bw/bw.js emulates the CLI, matching its --response envelopes and reproducing two of its shipped bugs, and the server runs as a real child process driven by the MCP SDK client. The load-bearing test plants a sentinel string in every secret and fails if it appears anywhere a model could read.

src/index.ts      server bootstrap, instructions, shutdown
src/config.ts     settings, paths, URL validation
src/bw.ts         CLI wrapper: re-entrant lock, minimal environment, response parsing
src/session.ts    the session key, sign-in, unlock, idle lock
src/vault.ts      item operations, and the model-facing and card-facing projections
src/sanitize.ts   the untrusted-text screen and the result envelope
src/pending.ts    staged changes: unguessable ids, single use, ten-minute lifetime
src/prompt.ts     native dialogs
src/clipboard.ts  copy, and the clear that only fires if the value is still there
src/tools.ts      the tool surface
ui/card.html      the card's markup and theme
ui/card.ts        the card
scripts/          build, install, package, dialog and clipboard helpers
test/             unit tests, end-to-end tests, the fake CLI and dialog

Licence

Copyright (C) 2026 ShadowsDistant.

This program is free software: you can redistribute it and modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It is distributed without any warranty, without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for details.

The bundled Bitwarden CLI is redistributed under its own terms.