Content
# 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:
```json
{
"mcpServers": {
"rbw": {
"command": "npx",
"args": ["-y", "rbw-mcp"]
}
}
}
```
### Option Two: Local checkout
Requires that this repository be checked out locally. Once that's done:
```bash
npm install
npm run build
```
## Setup
1. **Install `rbw`**:
Follow the instructions for your platform on the official [rbw repository](https://github.com/doy/rbw). For example, on Debian/Ubuntu:
```bash
sudo apt-get update
sudo apt-get install rbw
```
2. **Configure `rbw`**:
Configure `rbw` to connect to your Bitwarden account.
```bash
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.
```bash
rbw unlock
```
The server will check if the vault is unlocked on startup.
## Testing
### Running unit tests
The project includes Jest unit tests.
```bash
# 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:
```bash
# 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`.
