bws-mcp-server

An MCP server that wraps the Bitwarden Secrets Manager CLI (bws), so any MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.) can list, read, create, edit, and delete secrets and projects.

Prerequisites

• Node.js 18+
• The bws CLI installed and on your PATH (default lookup: /usr/local/bin/bws — override with BWS_PATH)
• A Bitwarden Secrets Manager machine account with an access token scoped to the project(s) you want to expose

Install bws:

brew install bitwarden/bws/bws
# or see https://bitwarden.com/help/secrets-manager-cli/ for other platforms

Usage

The server speaks MCP over stdio, so you don't run it directly — you register it with your MCP client and the client launches it.

Claude Code / Claude Desktop

Add to your MCP config (e.g. ~/.claude.json or claude_desktop_config.json):

{
  "mcpServers": {
    "bws": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "bws-mcp-server"],
      "env": {
        "BWS_ACCESS_TOKEN": "0.xxxxxxxx...",
        "BWS_SERVER_URL": "https://vault.bitwarden.eu"
      }
    }
  }
}

Restart the client. The server's tools (bws_secret_list, bws_secret_get, etc.) become available to the model.

Environment variables

| Variable | Required | Default | Description | | --- | --- | --- | --- | | BWS_ACCESS_TOKEN | yes | — | Machine-account access token from Bitwarden Secrets Manager | | BWS_SERVER_URL | no | https://vault.bitwarden.eu | Use https://vault.bitwarden.com for the US region or a self-hosted URL | | BWS_PATH | no | /usr/local/bin/bws | Absolute path to the bws binary if it's not at the default location |

Tools

Secrets

• bws_secret_list — list secrets the access token can see (optionally filter by project_id)
• bws_secret_get — fetch a single secret by UUID
• bws_secret_create — create a secret (key, value, project_id, optional note)
• bws_secret_edit — update key / value / note / project of an existing secret
• bws_secret_delete — delete one or more secrets by UUID (irreversible)

Projects

• bws_project_list — list projects
• bws_project_get — fetch a project by UUID
• bws_project_create — create a project
• bws_project_edit — rename a project
• bws_project_delete — delete one or more projects by UUID (irreversible)

All write operations execute immediately — there is no confirmation step. Scope your access token to the smallest project set that gets the job done.

Multiple environments

If you want separate dev and prod vaults available to the same client, register the server twice with different names and tokens:

{
  "mcpServers": {
    "bws-dev":  { "type": "stdio", "command": "npx", "args": ["-y", "bws-mcp-server"], "env": { "BWS_ACCESS_TOKEN": "0.devtoken..." } },
    "bws-prod": { "type": "stdio", "command": "npx", "args": ["-y", "bws-mcp-server"], "env": { "BWS_ACCESS_TOKEN": "0.prodtoken..." } }
  }
}

Development

git clone https://github.com/<you>/bws-mcp-server
cd bws-mcp-server
npm install
npm run build
BWS_ACCESS_TOKEN=0.xxx... node dist/index.js

License

MIT