Bitwarden MCP Hello World¶

This guide configures Bitwarden MCP and fetches a known secret from your vault as a first working example.

Scope¶

Example target:

Vault: ai-sandbox
Collection: AI_Shared
Item: hello-world
Username: hello

1. Configure local credentials¶

Bitwarden MCP uses environment variables. Store them in your local .env file (already ignored by git).

BW_SESSION="<paste output from bw unlock --raw>"
# Optional for org admin API features:
# BW_CLIENT_ID="organization.<id>"
# BW_CLIENT_SECRET="<secret>"

Refresh the session token whenever needed:

bw login
bw unlock --raw

2. Confirm MCP server wiring¶

The repository registers Bitwarden in .mcp.json using a local Docker container (ghcr.io/bitwarden/mcp-server:latest).

Validate prerequisites and MCP health:

just mcp-health

3. Fetch the hello-world secret through MCP¶

In your MCP-capable client, run a prompt similar to:

Use the bitwarden MCP server to get the login item named hello-world
from vault ai-sandbox and collection AI_Shared, then return only the
username and password fields.

Expected result pattern:

Username: hello
Password: <redacted secret value>

4. CLI fallback verification (optional)¶

If you need a local check independent of MCP:

bw sync
bw list items --search hello-world | jq '.[0] | {name, login: {username, password}}'

5. Kagi API key workflow¶

Use Bitwarden as the source of truth for Kagi credentials, then sync to .env:

just bw-kagi-key-pull

This command reads the Bitwarden item named Kagi API Key and upserts KAGI_API_KEY in your local .env without printing the secret value.

Troubleshooting¶

Invalid session: regenerate BW_SESSION with bw unlock --raw.
No matching item found: verify vault, collection, and item names exactly.
Permission issues: confirm your account can access collection AI_Shared.