# 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`.