icoretech/warden-mcp

**Vaultwarden / Bitwarden MCP server for credential-aware AI agents.**
warden-mcp lets MCP clients search, create, update, move, and read
Vaultwarden or Bitwarden vault items through the official Bitwarden CLI (bw).
It is built for agents and automation that need credentials, TOTP codes, secure
notes, attachments, Sends, folders, organizations, and collections without
re-implementing Bitwarden client-side crypto.
Use it when an agent needs to log in to real systems during a browser or admin
workflow, but you do not want passwords hardcoded in prompts, config files, or
one-off scripts.
Quick Start
Use stdio mode when a local MCP host launches the server directly. It is the
simplest and most portable setup for desktop agents.
Prerequisites:
- Node.js 22.x
- npm 10.x
- a Vaultwarden or Bitwarden account
- either a Bitwarden API key pair or username/password login
Run the server:
Username login also works:
If the package is useful, star the repository
so other agent builders can find it.
Install In MCP Hosts
Most local hosts should use stdio. The examples below use API-key auth; replace
BW_CLIENTID and BW_CLIENTSECRET with BW_USER if you prefer username login.
Claude Code
Codex
Codex TOML config:
startup_timeout_sec = 30 gives npx enough time for a cold first launch.
Cursor, Claude Desktop, And JSON Config Hosts
Common locations:
| Host | Config file |
| --- | --- |
| Cursor | ~/.cursor/mcp.json or .cursor/mcp.json |
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Codex | ~/.codex/config.toml |
Why Use It
- **Agent login flows** - fetch usernames, passwords, and TOTP codes during real
browser automation without storing secrets in the agent prompt
- **Safe by default** - secret fields stay redacted unless a tool supports
reveal: true and the client explicitly asks for it
- **Vault administration** - create, update, move, restore, and delete common
Bitwarden item types, folders, organization collections, attachments, and Sends
- **Shared HTTP mode** - one long-running service can front multiple vault hosts
or identities through per-request X-BW-* headers
- **Text-only client support** - safe identifiers are mirrored into text output
for MCP hosts that ignore structuredContent
- **Vaultwarden-first CI** - the integration suite exercises real local
Vaultwarden and bw auth/session flows, not only mocked SDK behavior
How It Works
warden-mcp shells out to bw and keeps profile state under
KEYCHAIN_BW_HOME_ROOT. In HTTP mode, profile selection and credentials come
from request headers. In stdio mode, credentials are loaded from BW_* env vars
when the process starts.
The HTTP server exposes:
| Endpoint | Purpose |
| --- | --- |
| GET /healthz | liveness check; does not validate vault credentials |
| GET /metricsz | session and runtime guardrail metrics |
| /sse?v=2 | MCP Streamable HTTP endpoint |
Run As A Shared HTTP Service
HTTP mode is useful when one service should serve multiple clients or multiple
vault profiles.
Start the server:
Verify liveness:
MCP tool calls must include these headers unless env fallback is explicitly
enabled:
| Header | Meaning |
| --- | --- |
| X-BW-Host | HTTPS origin only, for example https://vaultwarden.example.com |
| X-BW-Password | master password used to unlock the vault |
| X-BW-ClientId | Bitwarden API key client id |
| X-BW-ClientSecret | Bitwarden API key client secret |
| X-BW-User or X-BW-Username | username/email alternative to API key login |
| X-BW-Unlock-Interval | optional unlock interval in seconds; default 300 |
Example HTTP MCP config for hosts that support custom headers:
Some browser-hosted MCP clients can connect to an HTTP/SSE endpoint but cannot
send custom X-BW-* headers. For those clients, run a single-tenant HTTP server
with env fallback:
Only use KEYCHAIN_ALLOW_ENV_FALLBACK=true behind a trusted network boundary.
Every client that can reach the endpoint inherits the configured vault identity.