Give your AI assistant a Bitwarden account of its own
to sign up and sign in with. It finds, creates and updates logins, generates
passwords and hands one out only to type it, computes 2FA codes, keeps other
secrets (an API token, a key file) in secure notes, moves items between an
organization's collections, and checks passwords against Have I Been Pwned. It
is also a passkey authenticator: it registers passkeys and signs WebAuthn
sign-ins with them, stored the way Bitwarden's own apps store passkeys, so
either can use the other's. create_login, update_login, create_note,
move_item, create_passkey and import_passkeys write; delete_passkey
removes one passkey from its login, and nothing else deletes. Nothing exports
or changes settings, and no tool is money.
You need a Bitwarden account set aside for the agent, not your personal
vault (any plan: Premium is not needed), with its personal API key and master
password each in a file. Every call runs Bitwarden's CLI, so tools take
seconds, not milliseconds. The account is for the agent's own identities:
your own passkeys belong on your own devices.
What you can ask
- "Create a login for example.com with the username [email protected] and a
32-character password without symbols."
- "Which logins do we have saved for example.com?"
- "What is the current 2FA code for the Example Shop login?"
- "Generate a new password for the Example Shop login, and keep the old one in
case the site refuses the change."
- "Is the password of any of our Example Cloud logins in a known breach?"
- "Store the key in example-key.json as a secure note called 'Example Cloud
deploy key'."
- "Move the Example Shop login into the Shared collection."
- "Which passkeys does the vault hold for example.com?"
- "Import the passkeys in example-export.json, then delete the file."
Install
[Install in VS Code] [Install in Cursor] [Download for Claude Desktop]
With Claude Code:
Claude Desktop (Settings, Developer, Edit Config) and most other clients read the same command as JSON:
Each runs the published package on Node 22.19 or newer. VS Code and the Claude Desktop bundle ask for each setting as they add the server; leave an optional one empty. Cursor reads each from your environment instead (${env:BITWARDEN_CLIENT_ID_FILE} and so on), so set them before you start Cursor. The commands above set only what is required; Configuration has the rest.
From a clone
In a JSON configuration, the command is node and its one argument the full path of servers/bitwarden/dist/index.js. To share one running copy between several clients over HTTP, see docs/deploying.md.
The official CLI, @bitwarden/cli (pinned to 2026.10.0), is a dependency of
the package: npx and npm ci install it with the server, which runs it
under its own Node and never uses a bw on your PATH.
Configuration
BITWARDEN_CLIENT_ID, BITWARDEN_CLIENT_SECRET and
BITWARDEN_MASTER_PASSWORD are read only when their _FILE twin is unset.
Prefer the files: a variable is visible to every process of the same user. A
named file that is missing or empty is a config error, never a fallback to
the variable. Without the secrets the server still starts and lists its
tools, and each call answers a config error naming what is missing.
password_file, a note field's file and the export import_passkeys takes
are read from MCP_FILE_ROOTS; that
and the other variables every server shares are in
docs/configuration.md.
Getting the API key and master password
- Create a Bitwarden account for the agent, on any plan, with a strong
master password. Keep a copy where a person can recover it.
- In the web vault, open Settings, Security, Keys, and choose View API key.
- Write the
client_id (it looks like user.<uuid>) to the first file, the
client_secret to the second, and the master password to the third, each
readable by the server's user only.
- Optionally, create a free organization with a collection for the agent's
logins, set
BITWARDEN_DEFAULT_COLLECTION to it, and invite your own
account. You then see what the agent saves, and can lend it a login by
putting it in a second collection.
First run
- Ask your assistant to run Bitwarden's
health check. It answers with the
account's email, the server, the last sync, how many logins the vault
holds, and the organizations and collections it can file into. The first
call after a start logs in, unlocks and syncs, so it is the slowest. A
refused API key or master password shows up here as auth.
- To sign up somewhere, the assistant calls
create_login first, so the
password is stored before the site sees it, then get_password to type it.
- Passkeys need a program in the browser's place: whatever handles the
site's WebAuthn request (a browser extension, an automation driver) builds
the client data, checks the site's RP ID against the page's origin, and
calls
create_passkey or assert_passkey with the client data's hash.
The answer is what a browser hands back to the page.
Tools
read changes nothing in the vault; write adds an item or changes one.
Only delete_passkey removes anything: one passkey, from a login that stays.
Logins and notes
Passkeys
get_password, get_field and totp return a secret and are still read:
the account holds the agent's own logins, made for it to use without asking
(src/mcp/policy.ts). What they return is for typing or piping where it goes,
never for a file, a commit, a message or a reply. Keep your own passwords in a
vault this account cannot reach, and lend it one through a shared collection.
assert_passkey is read on the same terms: it hands out a signature, as
get_password hands out a password, and writes only a counter that is already
above 0. No tool returns a passkey's private key.
Troubleshooting
config. A secret is missing, or its file is missing or empty. Set
BITWARDEN_CLIENT_ID_FILE, BITWARDEN_CLIENT_SECRET_FILE and
BITWARDEN_MASTER_PASSWORD_FILE as Configuration says.
auth: "bw login --apikey: ..." or "bw unlock: ...". Bitwarden refused the
API key or the master password. If either changed in the web vault, update the
file the server reads it from.
not_found. No item has that id. find_logins lists what exists, with the
ids the other tools take.
input. The arguments cannot become a request, and nothing was sent; the
message says why. Most often: a login that already has a different
authenticator key (pass replace_totp: true, and the old key is kept), a
Steam key (not standard TOTP), a collection the account does not have
(health lists them), an edit to a secure note (notes are never edited), or
a move_item that would take an item out of its organization or out of the
account's own vault (the message says what to do instead).
cli. The CLI ran and said no: a network failure, a refused edit, or a
call past 90 seconds. Retry once; if it persists, run health and read the
server's log. If create_note failed without saying whether the note was
saved, look for it with find_logins before trying again.
unavailable. Have I Been Pwned could not be read, and the vault was not
changed. Retry in a minute; a deployment that limits its hosts must allow
api.pwnedpasswords.com.
no_credential. No passkey in the vault can answer that sign-in: none
for the RP ID, none the site's allow list names, or none discoverable when the
request names no passkey. list_passkeys shows what the vault holds.
several. More than one passkey can answer a request that names none.
The error's candidates lists them, without keys; call again with
credential_id set to the account you mean.
excluded. The site's exclude list names a passkey the vault holds: it
already has one from this vault for the account. Sign in with it instead.
unsupported. The site accepts no ES256 key, which is the only kind this
vault makes (as Bitwarden's apps), or a stored passkey's key cannot sign.
cli: "Insecure URL not allowed. All URLs must use HTTPS." The CLI talks
to a server over HTTPS only. Serve a self-hosted Bitwarden or Vaultwarden over
HTTPS; if your own authority signed its certificate, set NODE_EXTRA_CA_CERTS.
BITWARDEN_SERVER seems ignored. It applies when the CLI first logs in,
and a state folder logged in to another server keeps that one. Start from an
empty BITWARDEN_STATE_DIR to switch.
How it works
The CLI. Calls run the official CLI one at a time, because each run
reads and writes its single data.json. The process keeps only the session
key from bw unlock; after a restart, the next call logs in and unlocks
again. Calls that arrive while there is no key share that one unlock: every
bw unlock stores the vault's key under a new session key and the one before
stops opening it, so two unlocks at once left one call holding a stale key.
Secrets reach the CLI through its environment or stdin, never its
arguments, which every local user can read. As a child process, the CLI is not
covered by MCP_EGRESS_ALLOW (docs/configuration.md).
2FA codes are computed in src/domain/totp.ts, because Bitwarden reserves
bw get totp for Premium. A new key is checked strictly (base32, at least 16
characters) and stored before you confirm 2FA on the site, and the result
carries the current code computed from the stored key: if the site accepts
it, the key was stored exactly. A different key already on the login is
replaced only with replace_totp, and kept in a hidden field
(totp replaced <date>), so a mistaken replacement never locks the account.
Passwords going in. A generated password never passes through the model:
create_login stores it and returns none, and get_password hands it out to
type into the site. An existing password goes in as password, or as
password_file (by path inside MCP_FILE_ROOTS, or as content_base64 with
its sha256 from a script), so a long key is never retyped; the result gives
passwordLength, never the password. Generated passwords are 12 to 128
characters.
Other secrets. create_note keeps each in a custom field of a secure
note, hidden unless the call says otherwise. A field read from a file is taken
whole and exactly (every line, a final line ending and a byte-order mark
kept), and what the vault stored is read back and compared with what was
sent; compare the SHA-256 and size in the result with the source before you
delete it. Bitwarden refuses a field over 5,000 characters and a note's text
over 10,000 once encrypted, which is 3,695 and 7,439 bytes of plain UTF-8
(src/domain/note.ts). A service account's JSON key or a 4,096-bit PEM key
fits; a longer value or a binary file is refused before anything is sent
(encode it first, base64 -w0). The note's plain notes say what the secret
is and where it is used, since get_login shows them to anyone.
Nothing is lost by an edit. A rotated password is stored at once, so it
survives a session that ends before the site is updated, and the one it
replaced stays in Bitwarden's password history: get_password with
previous: true reads it, should the site refuse the new one. append_notes
adds a line to the notes (recovery codes, answers) where notes replaces
them.
Moving between collections. move_item replaces an item's collections
with the one named, through bw edit item-collections. An item already in
exactly that collection is answered as it is, and nothing is sent, so the call
is safe to repeat. After a move the server syncs and reads the item back, and
the answer is what Bitwarden holds rather than what the CLI printed. A move
stays inside the item's own organization: see Limitations.
Passkeys. The vault answers WebAuthn as an authenticator does: it gets
the RP ID, the client data's hash and the credential ids a site named, never
the page, and answers authenticator data and a signature, or an attestation
object. The program in the browser's place builds the client data, checks the
RP ID against the page's origin and assembles the credential a page receives.
Everything about the stored form and the answers follows Bitwarden's own
authenticator, so a passkey made here signs in Bitwarden's apps and one they
made signs here. Bitwarden documents what a person sees: a login keeps
one passkey,
and passkeys travel in its
JSON exports.
The fields are in its source, bitwarden/clients at the tag
cli-v2026.10.0 (commit b449ac1d255784380d75ef026343198891286be7):
libs/common/src/platform/services/fido2/fido2-authenticator.service.ts,
credential-id-utils.ts, guid-utils.ts and
libs/common/src/models/export/fido2-credential.export.ts. In short:
- A passkey lives in a login's
fido2Credentials, one per login, with
keyType public-key, keyAlgorithm ECDSA, keyCurve P-256, and
keyValue the private key as PKCS#8 in base64url. The CLI's JSON writes
counter and discoverable as text ("0", "true"); a JSON boolean would
be stored as false.
- The credential id is a random GUID, and a site knows it by the GUID's 16
bytes; an id from another provider is stored as
b64. and its base64url.
- The AAGUID is Bitwarden's,
d548826e-79b4-db40-a3d8-11116f7e8349, since the
passkey lives in a Bitwarden vault. The flags say user present, backup
eligible and backed up, and user verified only when the caller says so.
- The counter starts at 0, and a 0 is never advanced, so signing with a
passkey made here or in Bitwarden's apps writes nothing to the vault. A
passkey imported with a counter above 0 is advanced and stored, from a
fresh sync, before it signs.
- A new passkey goes into the login named by
item_id, else into the one
login saved for that site with that username and no passkey, so an
identity's password, 2FA key and passkey stay one item, else into a new
login.
bw edit item replaces a login with what it is given, so an edit that left
fido2Credentials out would drop the passkey: every edit here starts from the
item as read, and scripts/integration.ts proves that create_login,
update_login and the passkey tools keep passkeys through the pinned CLI. It
runs the built server against a throwaway account on a local Vaultwarden and
checks every registration and signature with an independent verifier
(@simplewebauthn/server); its header says how to run it.
Breached passwords. check_exposed uses Have I Been Pwned's keyless
range API: the first five hex characters of the password's SHA-1 go out, and
the answer (every hash suffix in that range with its count, padded with
decoys) is searched here. The password, its full hash and the suffix never
leave the server. This is the one request the server makes itself.
npx tsx scripts/smoke.ts drives the built server against a real account,
read-only unless given --write, which creates a login and a secure note
named "mcp smoke test" and "mcp smoke test note". Nothing here deletes them,
so remove them in the web vault afterwards.
Limitations
- No export, no settings, no attachments, no Sends, and no delete but one
passkey's: only what an agent needs to sign up and sign in, and nothing
else that loses data.
- Passkeys are ES256 only, as in Bitwarden's apps, with an attestation of
format none. No extension (PRF, large blobs) is answered: the program in the
browser's place answers
credProps itself, from discoverable.
- The import reads Bitwarden's JSON export (not encrypted) or one exported
item. The FIDO Alliance's Credential Exchange Format is not read yet.
- Moves stay inside an organization. Bitwarden encrypts an
organization's items with that organization's key, so moving an item out
of the account's own vault hands it to the organization, and Bitwarden has
no move from one organization to another.
move_item refuses both and says
what to do in the web vault instead.
- Logins and secure notes only; cards and identities are not read. A
secure note is created and read, never edited: a changed secret is a new
note.
- Steam's authenticator codes are not standard TOTP and are refused.
- Seconds, not milliseconds. Every call waits for the CLI: the first after
a start logs in, unlocks and syncs, and a tool that runs it several times
takes several seconds.
Other servers for Bitwarden
Searched 2026-10-15. Bitwarden publishes a server and a separate protocol;
one community server stands out:
@bitwarden/mcp-server, Bitwarden's own: stdio only, and by its own
warning never to be hosted. It unlocks the vault from a session key in an
environment variable, or through a native password dialog that refuses to
run headless. It administers the whole vault and organisation, deleting
items, Sends, attachments and device approvals included, and hands secrets
to the model: get returns an item or its password as text, generate the
new password, and create_item takes the password as an argument.- Bitwarden's Agent Access, an early-preview protocol and CLI, not an MCP
server: it fetches one credential at a time from a paired vault and can
inject it into a process's environment, unseen by the model, but cannot
create or update logins.
@icoretech/warden-mcp on npm, the most active community server: stdio
or HTTP, the API key and master password in environment variables (or each
HTTP request's headers), no authentication of its own. It redacts secrets
unless a call asks for reveal, and can always redact, stronger than this
one on reads; but a generated password must be revealed to be stored, and
its 2FA codes come from the CLI, which on bitwarden.com needs Premium.
This one is the narrow surface an agent needs to sign up and sign in.
create_login and rotate_password generate and store a password without
returning it, so it never passes through the model on the way in; only
get_password, get_field and totp return a secret, for typing. Its 2FA
codes work on a free account, and a new authenticator key is checked, stored
and proven by the current code. It is also a WebAuthn authenticator whose
private keys never leave it. Nothing exports, the one delete is a single
passkey's, and it runs over HTTP as its own service, unlocking itself from
secrets held in files.
