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

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

An MCP server that gives Claude access to a self-hostedVaultwarden or Bitwarden vault through the officialBitwarden 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 thepublished Bitwarden CLI. Read SECURITY.md before pointing it at a vault you careabout.

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 acopy button next to it. Ask for a new one and you get a filled-in draft with a generated passwordthat saves when you press Save, and not before.

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 lightand dark themes.

Reveal shows a secret for thirty seconds, then hides it. Copy never displays it at all: theserver writes the value straight to your clipboard and clears it thirty seconds later, tagged soWindows clipboard history and cloud clipboard skip it. Items you flagged "master passwordre-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 isthe 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 thelatest 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, masterpassword, 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 [email protected]

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 [email protected]

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. Pointyour 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": "[email protected]"
      }
    }
  }
}

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 youtype 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

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

Settings

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

Tools

⧉ marks the tools that draw a card.

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

Troubleshooting

"The Bitwarden CLI is not installed." The bundled CLI did not survive the install. Re-runnpm 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 theresult as BW_SESSION.

"Could not reach the vault server." Check the address in your settings and that the instanceis 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 notwritten 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 setVW_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 --responseenvelopes and reproducing two of its shipped bugs, and the server runs as a real child processdriven by the MCP SDK client. The load-bearing test plants a sentinel string in every secret andfails 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 GNUGeneral Public License as published by the Free Software Foundation, either version 3 of theLicense, or (at your option) any later version. It is distributed without any warranty, withouteven the implied warranty of merchantability or fitness for a particular purpose. See theGNU General Public License for details.

The bundled Bitwarden CLI is redistributed under its own terms.