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 provides two complementary interfaces:

• CLI-based tools: Personal vault management and organization operations using the Bitwarden CLI
• API-based tools: Enterprise organization administration using the Bitwarden Public API

This dual approach allows AI models to securely manage both personal vault items and organization-level resources through defined tool interfaces.

Prerequisites

• Node.js 22
• For CLI operations: Bitwarden CLI (bw) installed, authenticated, and valid session token
• For API operations: Bitwarden organization with API access and valid client credentials

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

The server supports two authentication methods:

Option A: CLI Authentication (for personal vault operations)

1. Install Bitwarden CLI:

   npm install -g @bitwarden/cli
   

2. Log in to Bitwarden:

   bw login
   

3. Get session token:

   export BW_SESSION=$(bw unlock --raw)
   

Option B: API Authentication (for organization management)

1. Create API credentials in your Bitwarden organization settings

2. Set environment variables:

   export BW_CLIENT_ID="your_client_id"
   export BW_CLIENT_SECRET="your_client_secret"
   

3. Optional: Set custom API URLs (if using self-hosted):

   export BW_API_BASE_URL="https://api.bitwarden.com"
   export BW_IDENTITY_URL="https://identity.bitwarden.com"
   

Note: You can use both authentication methods simultaneously for full functionality.

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:

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 comprehensive Bitwarden functionality through two authentication methods:

CLI Authentication is used for:

• Personal vault operations (items, folders, passwords)
• Quick organization queries (list members, collections)
• Organization member confirmation workflows
• Collection creation and editing
• Item collection assignments

API Authentication is used for:

• Full organization administration (members, groups, policies)
• Bulk operations and automation
• Advanced permission management
• Audit log retrieval
• Subscription management

Note: You can use both authentication methods simultaneously. The CLI tools are lighter-weight for simple operations, while API tools provide comprehensive organization management.

Personal Vault Tools (CLI Authentication)

Session Management

Vault Items and Folders

Organization Operations (CLI)

Note: Device approval commands are only available to organization admins/owners for managing trusted device approval requests.

Organization Management Tools (API Authentication)

Collections Management

Members Management

Groups Management

Policies Management

Organization Management

Events and Auditing

Manual testing

1. Start the server:

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

2. 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 sensitive credentials (BW_SESSION, BW_CLIENT_ID, BW_CLIENT_SECRET)
• Use environment variables for all sensitive configuration
• Validate all inputs using Zod schemas (already implemented)
• Test with non-production data when possible
• Monitor API usage through your organization's audit logs
• Use HTTPS for all API communications (default)
• 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

1. "Please set the BW_SESSION environment variable"

   • Run: export BW_SESSION=$(bw unlock --raw)

2. "BW_CLIENT_ID and BW_CLIENT_SECRET environment variables are required"

   • Set your API credentials: export BW_CLIENT_ID="your_id" and export BW_CLIENT_SECRET="your_secret"
   • Verify credentials are valid in your Bitwarden organization settings

3. API authentication failures

   • Check that your organization has API access enabled
   • Verify client credentials have appropriate permissions
   • Ensure you're using the correct API URLs for your instance

4. Tests failing with environment errors

   • Use the environment mocking helpers in tests
   • Ensure test cleanup with restoreEnvVars()

5. Inspector not starting

   • Check that the server builds successfully: npm run build
   • Verify Node.js version is 22

6. CLI commands failing

   • Verify Bitwarden CLI is installed: bw --version
   • Check vault is unlocked: bw status
   • Ensure valid session token: echo $BW_SESSION