Bitwarden Public API and Secrets Manager (unofficial)

Bitwarden MCP Server

Unofficial. This project is not made by, affiliated with or endorsed

by Bitwarden Inc. "Bitwarden" is a trademark of Bitwarden Inc. See

NOTICE.

A local Model Context Protocol (stdio) server that exposes Bitwarden's Public API (organization management) and the Bitwarden Secrets Manager (projects + secrets via the official SDK) as typed tools, read and write.

Intended use: an admin-facing MCP that lets an AI assistant manage members, groups, collections, policies, license seats, and Secrets-Manager data from a single host. Designed for a self-hosted Bitwarden instance, the official Bitwarden Cloud, or both.

Quick links: Architecture · Contributing · Security policy · Releasing · Changelog · Issues

Maintenance status

• Maintained on a best-effort basis by one maintainer (@mguttmann) in spare time. The author uses it in production. There is no support contract and no guaranteed response time.
• Security fixes take priority over features. Report vulnerabilities privately as described in SECURITY.md, never in a public issue.
• Dependency updates come from Dependabot; CI fails when a runtime dependency has a known advisory.
• Only the latest minor release gets fixes.
• Issues and pull requests are welcome; see CONTRIBUTING.md.

Features

• Public API: members, groups, collections, policies, events, organization import, subscription/licensing.
• Secrets Manager: projects and secrets via the official @bitwarden/sdk-napi (Zero-Knowledge crypto; cleartext names and values returned directly).
• Dual-instance aware: runs against a self-hosted Bitwarden instance, the official cloud, or both. Tools are wired to their instance at registration time so routing mistakes are impossible by accident.
• Hand-written tools for common flows (bw_member_list, bw_license_subscription_get, bws_secret_get_value, ...) plus the bw_raw_request escape hatch. With self-host and cloud configured the server lists 54 tools, with or without Secrets Manager; names and required parameters are pinned by tests/tool-contract.test.ts, and parameters are only ever added (optional), never removed or renamed.
• No generated tools in the shipped package: the generator for bw_ _ _raw tools exists (npm run generate), but the shipped spec (specs/public-api.spec.json) is empty, so 0 generated tools are registered. See Generated raw tools.
• Confirm-gated writes: every write tool returns a request preview unless invoked with confirm: "YES". Default is on. The model sets confirm itself, so this is friction, not a security boundary (see Safety model).
• Secret-safe by design: the metadata list never returns values; access tokens are managed in the web vault only.
• Token-budget-aware list defaults: list tools (bw_member_list, bw_collection_list, bw_group_list, bw_event_query) return slim projections by default to stay within LLM tool-call token budgets. See List-response shape for the opt-in to full nested responses.

What this MCP can and cannot do

Bitwarden's APIs expose different surfaces with different auth and crypto requirements. This MCP wraps everything that's _cleanly_ reachable. Some operations require Bitwarden's encryption layer (so we use the official SDK); others have no public API at all and need the web vault.

Can: Public API (organization and members)

Uses the Organization Public-API key (organization. / client_credentials / scope api.organization).

• List, get, invite, update, remove organization members
• Create, update, delete groups; manage group membership
• Update collection access per group (read / hide-passwords / manage); omitted fields of update tools keep their current value
• Read, set organization policies
• Query the event log
• Bulk-import groups + members
• Read full subscription details (PM seats, SM seats, storage, service-account slots)
• Adjust PM seats, PM storage, SM seats, SM service-account slots via the unified PUT /public/organization/subscription endpoint: the tools take a delta, send current + delta as the new total and read it back
• Cloud-only: license inspection on the cloud organization

Can: Secrets Manager (via the official Bitwarden SDK)

Uses the Machine-Account access token (BWS_ACCESS_TOKEN), exchanged through @bitwarden/sdk-napi which handles Bitwarden's Zero-Knowledge encryption.

• List, get, create, update, delete projects (visible to the configured MA)
• List secret metadata, fetch full secret incl. cleartext value, create, update, delete secrets

Cannot: these need a human in the web vault

These are not available to the credentials this server uses (organization API key, machine account access token). The SDK and the bws CLI don't offer them either.

• Create, update, delete Machine Accounts
• Assign projects to a Machine Account
• Create or rotate Machine Account Access Tokens
• List all Machine Accounts in the organization (machine accounts and access tokens can only be managed by a logged-in user in the web vault)
• Trigger a cloud to self-host license re-sync
• Read, grant or revoke a member's Secrets Manager access. Bitwarden's Public API neither returns nor applies accessSecretsManager; bw_member_grant_sm / bw_member_revoke_sm stay registered but always return an error.
• Per-user collection access (bw_collection_update rejects a non-empty users list; give members direct access via bw_member_update collections), group accessAll (removed upstream), and filtering events by IP address.

For all of these: use the web vault at https:// /#/sm/{orgId}/.

Requirements

• Node.js 22.12 or newer (engines.node >=22.12; CI tests 22, 24 and 26).
• A Bitwarden Public-API key (client_id / client_secret) for at least one instance (self-host or cloud).
• For Secrets Manager: a Machine-Account access token (from the web vault).

Platform support

This MCP works on any platform with Node.js 22.12 or newer for all Public API features (members, groups, collections, policies, events, license adjustments).

The Secrets Manager features (bws_project_*, bws_secret_*) depend on @bitwarden/sdk-napi (1.0.0, an optional dependency, not MIT licensed), which ships native Rust binaries as optional per-platform packages. The lockfile contains @bitwarden/sdk-napi-darwin-arm64, -darwin-x64, -linux-x64-gnu and -win32-x64-msvc:

On unsupported platforms the MCP still starts and all Public-API tools work normally. The bws_project_* and bws_secret_* tools stay registered and return "Secrets Manager SDK not available on this platform" at call time; the load error is logged once at startup as a warn line.

If Bitwarden releases an SDK version with binaries for a new platform, updating the dependency and the lockfile picks it up; no code change is needed.

Installation

The package is the-real-bitwarden-mcp on npm, published from GitHub Actions with provenance. Its bin is bitwarden-mcp. Configuration is the same for every path (see Configuration).

Local MCP clients (npx or npm install)

npx fetches and starts the package; pin a version so an update is a decision, not a side effect of a restart:

npx -y the-real-bitwarden-mcp@<version>

Or install it once and start the bin:

npm install -g the-real-bitwarden-mcp@<version>

bitwarden-mcp

See Connector wiring for client configs.

Gateways and servers (pinned, from npm)

Install a pinned version with a lockfile and start it with node, without npx and without install scripts. Once, in an empty directory:

npm init -y

npm install --save-exact the-real-bitwarden-mcp@ # writes package-lock.json

Commit or keep package.json and package-lock.json. On every deploy:

npm ci --omit=dev --ignore-scripts

node --env-file=/path/to/.env node_modules/the-real-bitwarden-mcp/dist/index.js

The package has no install script and no runtime dependency in devDependencies, so --omit=dev --ignore-scripts is a complete install. The Secrets Manager SDK binary is an optional per-platform package that npm selects by OS and CPU; it needs no script either.

From source

git clone https://github.com/mguttmann/the-real-bitwarden-mcp.git

cd the-real-bitwarden-mcp npm ci # also pulls the platform-specific SDK binary cp .env.example .env

Fill in .env, see "Configuration".

npm run build node --env-file=.env dist/index.js

The SDK binary is an optional dependency: npm ci succeeds even on unsupported platforms (the binary is simply not present, and SM tools return a clear "not available" message).

Generated raw tools

npm run refresh-spec pulls the Swagger document of your self-host instance into specs/public-api.spec.json, and npm run generate builds one bw_ _ _raw tool per operation from it. The shipped spec is empty ({"paths": {}}), so a normal build registers 0 generated tools. Generating tools changes the tool list; if the server runs behind a gateway that pins the tool surface, treat that as a deploy change.

Configuration

All values are environment variables. They come from the process environment (for example node --env-file=.env, or the env block of an MCP client config). When the server is not started with --env-file (or --env-file-if-exists), a .env file in the process working directory is read as well and only fills variables that are not already set; with --env-file it is ignored. At least one instance must be fully configured, otherwise the server refuses to start. A partially configured instance (some but not all four variables) is also fatal, and so is an API base or identity URL that is not an http:// or https:// URL or that has a query or fragment (the error names the variable). Invalid values of the optional numeric and boolean variables fall back to the default.