bitwarden-mcp

English | 中文

Bitwarden MCP server for Claude — exposes the Bitwarden Public API's organization member and vault group management as MCP tools, focused on inviting members and assigning them to vault groups ("密码库群组邀请").

Tech stack: Python 3.12 + uv + FastMCP (Starlette/uvicorn)

关联需求：PRD-15544（[Self-built MCP] MSPbots Integration - Bitwarden）。完整调研见 vendor-mcp-template/prd/Bitwarden.md。

Out of scope: Bitwarden Send (temporary secure credential links) is intentionally not implemented. The Public API does not allow management of individual vault items, and Send requires a stateful, unlocked local bw CLI vault — incompatible with this service's stateless, multi-tenant gateway model.

Quick Start

cd bitwarden-mcp
uv sync

# stdio mode (for Claude Desktop / CLI), single shared credential set from env
BITWARDEN_CLIENT_ID=organization.xxxx BITWARDEN_CLIENT_SECRET=xxxx uv run bitwarden-mcp

Related MCP server: bitwarden-agent-vault-mcp

Authentication

This service is stateless: it never stores or persists Bitwarden credentials. Credentials are either supplied once via environment variables (local dev, AUTH_MODE=env), or per-request via HTTP headers (AUTH_MODE=gateway, production).

Bitwarden's Public API uses OAuth2 Client Credentials (grant_type=client_credentials, scope=api.organization). On every tool call, this service exchanges the caller's client_id + client_secret for a short-lived access_token (~1h TTL) and uses it immediately — the token is not cached across requests, in order to fully comply with the "no persisted credentials" requirement. This adds one extra Identity round trip per call.

Gateway mode HTTP headers (AUTH_MODE=gateway)

Missing either of the two required headers on a /mcp request returns 401 with a required_headers list.

Env mode variables (AUTH_MODE=env, local dev only)

Get credentials: as an organization Owner, go to Admin Console → Settings → Organization info → API Key. Requires a paid organization plan (Teams/Enterprise) — free personal Bitwarden accounts have no organization and cannot use the Public API.

Claude Desktop Setup

{
  "mcpServers": {
    "bitwarden": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/bitwarden-mcp", "bitwarden-mcp"],
      "env": {
        "BITWARDEN_CLIENT_ID": "organization.xxxx",
        "BITWARDEN_CLIENT_SECRET": "xxxx"
      }
    }
  }
}

Transport Modes

stdio (Claude Desktop / CLI)

BITWARDEN_CLIENT_ID=organization.xxxx BITWARDEN_CLIENT_SECRET=xxxx uv run bitwarden-mcp

HTTP — single-tenant (env mode)

BITWARDEN_CLIENT_ID=organization.xxxx BITWARDEN_CLIENT_SECRET=xxxx \
MCP_TRANSPORT=http AUTH_MODE=env uv run bitwarden-mcp
curl http://localhost:8080/health

HTTP — gateway / multi-tenant (production)

MCP_TRANSPORT=http AUTH_MODE=gateway uv run bitwarden-mcp

Tool List

Base URL: https://api.bitwarden.com (default; overridable per-request, see Authentication).

Member type (role) enum: 0=Owner, 1=Admin, 2=User (default/regular Member), 3=Manager, 4=Custom. Member status enum (read-only): 0=Invited, 1=Accepted, 2=Confirmed.

Rate limits: Bitwarden does not publish specific Public API rate-limit numbers (unlike some other vendors). This service passes through 429 responses as-is if Bitwarden throttles a request.

Test Examples

tools/list (gateway mode)

curl -X POST http://localhost:8080/mcp \
  -H "x-bitwarden-client-id: organization.your_client_id" \
  -H "x-bitwarden-client-secret: your_client_secret" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

tools/call — invite a member

curl -X POST http://localhost:8080/mcp \
  -H "x-bitwarden-client-id: organization.your_client_id" \
  -H "x-bitwarden-client-secret: your_client_secret" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 2,
    "params": {
      "name": "bitwarden_invite_member",
      "arguments": {"email": "user@example.com", "type": 2}
    }
  }'

tools/call — assign a member to vault groups

curl -X POST http://localhost:8080/mcp \
  -H "x-bitwarden-client-id: organization.your_client_id" \
  -H "x-bitwarden-client-secret: your_client_secret" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 3,
    "params": {
      "name": "bitwarden_update_member_groups",
      "arguments": {"member_id": "<member-uuid>", "group_ids": ["<group-uuid>"]}
    }
  }'

Missing headers → 401

curl -i -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
# HTTP/1.1 401 Unauthorized
# {"error":"Missing credentials","required_headers":["x-bitwarden-client-id","x-bitwarden-client-secret"]}

API Reference

• Bitwarden Public API overview

• Public API OpenAPI/Swagger definition

• Member roles / access control

Known Limitations

• No Bitwarden Send support — out of scope by design (see top of this README).

• bitwarden_update_member_groups is a full replace, not an append — it mirrors the underlying PUT /public/members/{id}/group-ids semantics exactly. To add a member to one more group without removing existing ones, call bitwarden_list_member_groups first, merge in the new group id, then pass the full list.

• No documented Public API rate limits from Bitwarden — errors are passed through as-is.

• Token exchange happens on every tool call (no caching), which adds latency but keeps the service fully stateless per the SOP requirement.

• Requires a paid organization plan (Teams/Enterprise) with an organization API key generated; free personal accounts cannot use this service.