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 24+
• npm
• a Vaultwarden or Bitwarden account
• either a Bitwarden API key pair or username/password login

Run the server:

BW_HOST=https://vaultwarden.example.com \
BW_CLIENTID=user.xxxxx \
BW_CLIENTSECRET=xxxxx \
BW_PASSWORD='your-master-password' \
npx -y @icoretech/warden-mcp@latest --stdio

Username login also works:

BW_HOST=https://vaultwarden.example.com \
BW_USER=user@example.com \
BW_PASSWORD='your-master-password' \
npx -y @icoretech/warden-mcp@latest --stdio

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

claude mcp add-json warden '{"command":"npx","args":["-y","@icoretech/warden-mcp@latest","--stdio"],"env":{"BW_HOST":"https://vaultwarden.example.com","BW_CLIENTID":"user.xxxxx","BW_CLIENTSECRET":"xxxxx","BW_PASSWORD":"your-master-password"}}'

Codex

codex mcp add warden \
  --env BW_HOST=https://vaultwarden.example.com \
  --env BW_CLIENTID=user.xxxxx \
  --env BW_CLIENTSECRET=xxxxx \
  --env BW_PASSWORD='your-master-password' \
  -- npx -y @icoretech/warden-mcp@latest --stdio

Codex TOML config:

[mcp_servers.warden]
command = "npx"
args = ["-y", "@icoretech/warden-mcp@latest", "--stdio"]
startup_timeout_sec = 30

[mcp_servers.warden.env]
BW_HOST = "https://vaultwarden.example.com"
BW_CLIENTID = "user.xxxxx"
BW_CLIENTSECRET = "xxxxx"
BW_PASSWORD = "your-master-password"

startup_timeout_sec = 30 gives npx enough time for a cold first launch.

Cursor, Claude Desktop, And JSON Config Hosts

{
  "mcpServers": {
    "warden": {
      "command": "npx",
      "args": ["-y", "@icoretech/warden-mcp@latest", "--stdio"],
      "env": {
        "BW_HOST": "https://vaultwarden.example.com",
        "BW_CLIENTID": "user.xxxxx",
        "BW_CLIENTSECRET": "xxxxx",
        "BW_PASSWORD": "your-master-password"
      }
    }
  }
}

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

flowchart LR
    Agent["AI agent or MCP client"] --> Transport["stdio or Streamable HTTP"]
    Transport --> Server["warden-mcp"]
    Server --> BW["Bitwarden CLI (bw)"]
    BW --> Vault["Vaultwarden or Bitwarden"]
    Server --> State["per-profile bw state"]

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:

npx -y @icoretech/warden-mcp@latest

Verify liveness:

curl -fsS http://localhost:3005/healthz

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:

{
  "mcpServers": {
    "warden": {
      "url": "http://localhost:3005/sse?v=2",
      "headers": {
        "X-BW-Host": "https://vaultwarden.example.com",
        "X-BW-ClientId": "user.xxxxx",
        "X-BW-ClientSecret": "xxxxx",
        "X-BW-Password": "your-master-password"
      }
    }
  }
}

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:

BW_HOST=https://vaultwarden.example.com \
BW_CLIENTID=user.xxxxx \
BW_CLIENTSECRET=xxxxx \
BW_PASSWORD='your-master-password' \
KEYCHAIN_ALLOW_ENV_FALLBACK=true \
npx -y @icoretech/warden-mcp@latest

Only use KEYCHAIN_ALLOW_ENV_FALLBACK=true behind a trusted network boundary. Every client that can reach the endpoint inherits the configured vault identity.

For hosted clients that require HTTPS, put a reverse proxy, private tunnel, VPN, or equivalent protected endpoint in front of warden-mcp, then connect to:

https://warden-mcp.example.com/sse?v=2

Docker

docker run --rm \
  -p 127.0.0.1:3005:3005 \
  -v warden-mcp-data:/data \
  ghcr.io/icoretech/warden-mcp:latest

The production image runs as the non-root node user with uid/gid 1000, sets HOME=/data, and stores Bitwarden profile state under /data/bw-profiles by default. If you use a bind mount, make it writable by uid/gid 1000.

Runtime Requirements

warden-mcp requires Node.js 24+ when running from npm or source. The Docker image includes the supported Node runtime.

The server resolves bw in this order:

1. BW_BIN, when set
2. bundled @bitwarden/cli optional dependency, when installed
3. system bw from PATH

The bundled @bitwarden/cli version is currently 2026.6.0. This project keeps that version vetted instead of blindly tracking every upstream release, because auth and unlock behavior can change in ways that break automation.

If your package manager skips optional dependencies and bw is missing, install the CLI explicitly or point BW_BIN to a known binary:

npm install -g @bitwarden/cli@2026.6.0
BW_BIN=/absolute/path/to/bw npx -y @icoretech/warden-mcp@latest --stdio

Security Model

There is no built-in authentication layer in v1. Protect the transport before you expose it.

• Bind locally by default - use WARDEN_MCP_HOST=127.0.0.1, Docker -p 127.0.0.1:3005:3005, a firewall, VPN, or an authenticated reverse proxy
• Use TLS for HTTP mode - X-BW-* headers carry vault credentials
• Avoid env fallback on shared networks - KEYCHAIN_ALLOW_ENV_FALLBACK=true makes server-side vault credentials available to headerless clients
• Use read-only mode when writes are not needed - READONLY=true or KEYCHAIN_READONLY=true hides mutating tools and rejects direct write calls
• Use no-reveal mode for untrusted agent contexts - NOREVEAL=true or KEYCHAIN_NOREVEAL=true forces all secret-returning tools to stay redacted
• Keep debug logs off in production - do not enable KEYCHAIN_DEBUG_BW or KEYCHAIN_DEBUG_HTTP unless actively troubleshooting
• Restrict profile storage - protect KEYCHAIN_BW_HOME_ROOT, which stores local bw profile state
• Protect /metricsz if needed - it is unauthenticated for scraper compatibility and exposes runtime/session counters

Redacted fields include login passwords, TOTP seeds/codes, card numbers and codes, identity SSNs/passport/license numbers, hidden custom fields, SSH private keys stored through the secure-note convention, signed attachment URLs, and password history entries.

Configuration

Variable	Default	Purpose
PORT	3005	HTTP listen port
WARDEN_MCP_HOST	all interfaces	HTTP bind host
WARDEN_MCP_STDIO	false	force stdio mode without --stdio
MCP_APP_NAME	keychain-mcp	advertised MCP server name
TOOL_PREFIX	keychain	public tool namespace
TOOL_SEPARATOR	_	public tool separator; set . for legacy clients
KEYCHAIN_BW_HOME_ROOT	${HOME}/bw-profiles	root for per-profile bw state
KEYCHAIN_ALLOW_ENV_FALLBACK	false	allow HTTP calls to inherit server BW_* env
KEYCHAIN_SYNC_ON_WRITE	true	run bw sync before write operations
READONLY / KEYCHAIN_READONLY	false	hide and reject mutating tools
NOREVEAL / KEYCHAIN_NOREVEAL	false	force reveal: false server-side
KEYCHAIN_TEXT_COMPAT_MODE	unset	set structured_json for text-only clients
KEYCHAIN_SESSION_MAX_COUNT	32	max tracked HTTP sessions
KEYCHAIN_SESSION_TTL_MS	900000	inactive session TTL
KEYCHAIN_SESSION_SWEEP_INTERVAL_MS	60000	session cleanup interval
KEYCHAIN_MAX_HEAP_USED_MB	1536	memory fuse; set 0 to disable
KEYCHAIN_METRICS_LOG_INTERVAL_MS	0	periodic metrics logging; 0 disables

KEYCHAIN_TEXT_COMPAT_MODE=structured_json mirrors supported structuredContent into plain text. That helps MCP clients that only pass content[] to the model, but any revealed secret will also appear in the text transcript.

Tool Reference

Tool names default to keychain_*. Change the prefix with TOOL_PREFIX and the separator with TOOL_SEPARATOR.

Start with these:

• keychain_status - inspect raw bw status
• keychain_sync - pull latest vault data with bw sync
• keychain_search_items - find items by name, URI, username, folder, collection, or type
• keychain_get_item - read a full item by id, redacted by default
• keychain_get_username, keychain_get_password, keychain_get_totp - fetch common login values; password and TOTP require reveal: true
• keychain_create_login, keychain_update_item, keychain_move_item_to_organization - common write paths

Full tool groups:

Group	Tools
Vault/session	keychain_status, keychain_sync, keychain_sdk_version, keychain_encode, keychain_generate, keychain_generate_username
Items	keychain_search_items, keychain_get_item, keychain_update_item, keychain_create_login, keychain_create_logins, keychain_set_login_uris, keychain_create_note, keychain_create_card, keychain_create_identity, keychain_create_ssh_key, keychain_delete_item, keychain_delete_items, keychain_restore_item
Folders	keychain_list_folders, keychain_create_folder, keychain_edit_folder, keychain_delete_folder
Organizations and collections	keychain_list_organizations, keychain_list_collections, keychain_list_org_collections, keychain_create_org_collection, keychain_edit_org_collection, keychain_delete_org_collection, keychain_move_item_to_organization
Attachments	keychain_create_attachment, keychain_delete_attachment, keychain_get_attachment
Sends	keychain_send_list, keychain_send_template, keychain_send_get, keychain_send_create, keychain_send_create_encoded, keychain_send_edit, keychain_send_remove_password, keychain_send_delete, keychain_receive
Direct bw get helpers	keychain_get_username, keychain_get_password, keychain_get_totp, keychain_get_notes, keychain_get_uri, keychain_get_exposed, keychain_get_folder, keychain_get_collection, keychain_get_organization, keychain_get_org_collection, keychain_get_password_history

Notes:

• keychain_create_logins creates several independent login items in one call and reports per-item failures without aborting the whole batch
• keychain_set_login_uris replaces or merges a login item's URI list without editing the entire item payload
• keychain_delete_items supports bulk soft-delete or hard-delete by id
• keychain_get_item exposes safe attachment metadata, including id, fileName, and size, while redacting signed download URLs
• keychain_get_attachment accepts an attachment id or an unambiguous filename and returns { filename, bytes, contentBase64 }
• keychain_send_get returns owned Send metadata and text content; use keychain_receive with a Send accessUrl to receive shared Sends or download file Send bytes
• Ambiguous login lookups return AMBIGUOUS_LOOKUP with visible candidate ids; retry with the exact item id

Local Development

Use Docker Compose when you need the full Vaultwarden-backed stack.

cp .env.example .env
make up

make up starts local Vaultwarden, an HTTPS proxy for bw, bootstraps a test account, and runs the MCP server in the foreground.

Useful commands:

Command	Purpose
npm run dev	watch-mode server from source
npm run build	compile TypeScript to dist/
npm run start	run the compiled server
npm run lint	Biome autofix plus tsc --noEmit
npm run test	build, then run all compiled tests
npm run test:integration	build, then run compose-backed integration tests
npm run test:coverage	build, then run Node test coverage
make test	run the compose-backed Vaultwarden integration path
make test-org	run the organization-focused compose stack
make down	stop the local compose stack

For a quick live MCP smoke against local Vaultwarden, see agent-instructions/testing.md.

Compatibility

Vaultwarden is the continuously proven target in CI. Official Bitwarden compatibility is intended, but it is not continuously proven without a real Bitwarden tenant.

@bitwarden/cli upgrades are treated as compatibility decisions. The suite checks direct bw auth behavior, SDK behavior, and MCP integration behavior against a local Vaultwarden instance before a CLI bump should ship.

Known Limitations

• bw list items --search, and therefore keychain_search_items, does not reliably search inside custom field values
• SSH keys are stored as secure notes with standard fields until bw supports native SSH key item creation
• high-risk bw features such as export/import are intentionally not exposed
• Vaultwarden report pages are not mirrored as MCP tools; the current report-like helper is keychain_get_exposed

Project Links

• npm package: @icoretech/warden-mcp
• Docker image: ghcr.io/icoretech/warden-mcp
• Changelog: CHANGELOG.md
• Security policy: SECURITY.md
• Threat model: THREAT_MODEL.md
• Repository guidance: AGENTS.md

Contributing

Issues and PRs are welcome. Run npm run lint and the relevant test command before opening a PR; use make test when behavior depends on real Vaultwarden or bw interaction.

License

MIT