mcp-server by bitwarden - MCP Server

Bitwarden MCP Server

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

Prerequisites

Node.js 22
Bitwarden CLI (bw) installed and authenticated
Valid Bitwarden session token

Installation

Option One: Configuration in your AI app

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

{
  "mcpServers": {
    "bitwarden": {
      "command": "npx",
      "args": ["-y", "@bitwarden/mcp-server"]
    }
  }
}

Option Two: Local checkout

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

npm install
npm run build

Setup

Install Bitwarden CLI:
```
npm install -g @bitwarden/cli
```
Log in to Bitwarden:
```
bw login
```
Get session token:
```
export BW_SESSION=$(bw unlock --raw)
```

Testing

Running unit tests

The project includes Jest unit tests covering validation, CLI commands, and core functionality.

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

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

# Run specific test file
npm test validation.spec.ts

# Run tests matching a pattern
npm test -- --testNamePattern="validation"

Inspection and development

MCP Inspector

Use the MCP Inspector to test the server interactively:

# Start the inspector
npm run inspect

This will:

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

Available tools

The server provides the following Bitwarden CLI tools:

Tool	Description	Required Parameters
`lock`	Lock the vault	None
`unlock`	Unlock with master password	`password`
`sync`	Sync vault data	None
`status`	Check CLI status	None
`list`	List vault items/folders	`type` (items/folders/collections/organizations)
`get`	Get specific item/folder	`object`, `id`
`generate`	Generate password/passphrase	Various optional parameters
`create`	Create new item or folder	`objectType`, `name`, additional fields for items
`edit`	Edit existing item or folder	`objectType`, `id`, optional fields to update
`delete`	Delete vault item/folder	`object`, `id`, optional `permanent`

Manual testing

Start the server:

export BW_SESSION=$(bw unlock --raw)
node dist/index.js

Test with an MCP client or use the inspector to send tool requests.

Debugging

Enable debug logging by setting environment variables:

export DEBUG=bitwarden:*
export NODE_ENV=development

Check Bitwarden CLI status:
```
bw status
```
Verify session token:
```
echo $BW_SESSION
```

Security considerations

Never commit the BW_SESSION token
Use environment variables for sensitive configuration
Validate all inputs using Zod schemas (already implemented)
Test with non-production data when possible
Understand the security and privacy impacts of exposing sensitive vault data to LLM and AI tools. Using a self-hosted or local LLM may be appropriate, for example.

Troubleshooting

Common issues

"Please set the BW_SESSION environment variable"
- Run: export BW_SESSION=$(bw unlock --raw)
Tests failing with environment errors
- Use the environment mocking helpers in tests
- Ensure test cleanup with restoreEnvVars()
Inspector not starting
- Check that the server builds successfully: npm run build
- Verify Node.js version is 22
CLI commands failing
- Verify Bitwarden CLI is installed: bw --version
- Check vault is unlocked: bw status
- Ensure valid session token: echo $BW_SESSION