rbw-mcp

Model Context Protocol (MCP) server that enables interaction with the Bitwarden password manager vault via the rbw (Rust Bitwarden) command-line interface. The server allows AI models to securely communicate with a user's Bitwarden vault through defined tool interfaces.

Prerequisites

• Node.js 22
• rbw (Rust Bitwarden CLI) installed and configured.

Installation

Option One: Configuration in your AI app

Open up your application configuration, e.g. for Claude Desktop:

{
  "mcpServers": {
    "rbw": {
      "command": "npx",
      "args": ["-y", "rbw-mcp"]
    }
  }
}

Option Two: Local checkout

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

npm install
npm run build

Setup

1. Install rbw: Follow the instructions for your platform on the official rbw repository. For example, on Debian/Ubuntu:

   sudo apt-get update
   sudo apt-get install rbw
   

2. Configure rbw: Configure rbw to connect to your Bitwarden account.

   rbw config
   

3. Unlock your vault: Before running the MCP server, you must unlock your vault. This starts the rbw-agent and allows subsequent commands to run without prompting for a password.

   rbw unlock
   

   The server will check if the vault is unlocked on startup.

Testing

Running unit tests

The project includes Jest unit tests.

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm test -- --coverage

Inspection and development

MCP Inspector

Use the MCP Inspector to test the server interactively:

# Start the inspector
npm run inspect

This will:

1. Start the MCP server
2. Launch the inspector UI in your browser
3. Allow you to test all available tools interactively

Available tools

The server provides the following rbw CLI tools:

Tool	Description	Required Parameters	Notes
lock	Lock the vault by clearing cached keys from the agent.	None	Executes rbw lock.
unlock	Unlock the vault. This will trigger an interactive prompt for your master password if needed.	None	Executes rbw unlock.
sync	Sync vault data from the Bitwarden server.	None	Executes rbw sync.
status	Check if the vault is unlocked.	None	Executes rbw unlocked.
list	Lists items from the vault. Can be filtered by a search term.	Optional: search, ignoreCase	Executes rbw list --fields name,user,id,folder and filters results in-memory.
get	Get a specific field for an item (defaults to password).	id (required). Optional: field	Executes rbw get <id> or rbw get --field .... Use list to find the exact ID first.
code	Get a TOTP code for an item.	id	Executes rbw code <id>. Use list to find the exact ID first.
generate	Generate a secure password or passphrase. By default, generates a strong password with symbols.	Optional: length, diceware, noSymbols	Executes rbw generate.
delete	Delete an item from your vault.	id	Executes rbw rm <id>.
create	Create a new login item in your vault.	name (required). Optional: username, password, notes, uri	Executes rbw add. Uses EDITOR='tee' for non-interactive input.
edit	Edit the password and/or notes for an existing item in your vault.	id (required). Optional: password, notes	Executes rbw edit. Uses EDITOR='tee' for non-interactive input.

Security considerations

• Use rbw-agent: It is highly recommended to use rbw with its agent to handle the master password securely.
• Validate all inputs: All tool inputs are strictly validated using Zod schemas.

Troubleshooting

Common issues

1. "Vault is locked" error on startup

   • Run rbw unlock in your terminal before starting the server.

2. rbw command not found

   • Ensure that rbw is installed and that its location is in your system's PATH.

3. Tests failing

   • Ensure all development dependencies are installed with npm install.