jr2804 Using vaultwarden-mcp
vaultwarden-mcp exposes a Vaultwarden (Bitwarden-compatible) vault to AI
agents as fourteen MCP tools. You don't run the binary — the MCP host does. Your
job is to call the tools with the right arguments. This file is the lean
overview; details live in references/ and are read on demand.
The fourteen tools
Read (safe, idempotent):
| Tool | Purpose | account |
|---|---|---|
list_accounts |
list connected vault identities | — |
search |
find entries by name/username/URI (metadata only — no password) | optional |
get_cipher |
fetch one entry by id (full, including password) | required |
sync |
re-pull the vault from the server (refresh cache) | optional |
Write (mutate the vault):
| Tool | Purpose | account |
|---|---|---|
create_cipher |
create a login or secure note | required |
edit_cipher |
partial-overlay edit (change only the fields you send) | required |
soft_delete_cipher |
move to trash (reversible via restore) | required |
restore_cipher |
restore a trashed entry | required |
delete_cipher |
permanently destroy (irreversible) | required |
Folders (organize entries):
| Tool | Purpose | account |
|---|---|---|
list_folders |
list folder names in a vault | optional |
get_folder_id |
resolve a folder name to its id | required |
create_folder |
create a folder | required |
edit_folder |
rename a folder | required |
delete_folder |
delete a folder (entries move to No Folder) | required |
The two rules that trip up agents
accountis optional for reads, required for writes. A write must target one vault. If you don't know the label, search first (reads accept no account) and read theaccountfrom the result — or calllist_accounts.searchreturnspassword: nullby design. Useget_cipherfor the secret. The split keeps casual queries from dumping plaintext into context.
The standard lookup flow
search { query: "github" } → [ { id, name, username, uri, password: null } ]
get_cipher { cipher_id, account } → { ..., password, totp, notes, fields }
edit_cipher — the overlay rule (one-line summary)
Omit a field to keep it; send null to clear it; send a value to
set it. Don't send null when you mean "leave it alone" — that wipes it.
Deletion default
When a user says "delete," default to soft_delete_cipher (reversible). Use
delete_cipher (permanent) only when they say "permanently" / "forever", or
when cleaning up your own test entries.
When to read the references
| Need | Read |
|---|---|
| Exact param names, types, required vs optional, return shapes | references/tools-reference.md |
| Worked recipes: create login/note, edit overlay, rotation, delete flow | references/workflows.md |
| How to configure the server for an MCP client (Claude Desktop, CLI) | references/setup.md |
Bundled assets & scripts
assets/example-mcp-config.json— complete two-account example (MCP client config + the matchingsecretspec.toml+vaultwarden-mcp.toml).scripts/roundtrip-test.py— driver that exercises every write tool against a live server; useful for confirming writes work after setup. Run with--helpfor usage; secrets must be in the environment.