bitwarden/mcp-server
If you are the rightful owner of mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Bitwarden MCP Server facilitates secure interaction between AI models and a user's Bitwarden vault using the Model Context Protocol.
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)
- Run:
-
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
- Check that the server builds successfully:
-
CLI commands failing
- Verify Bitwarden CLI is installed:
bw --version
- Check vault is unlocked:
bw status
- Ensure valid session token:
echo $BW_SESSION
- Verify Bitwarden CLI is installed: