Warden MCP

Warden MCP

What is Warden MCP about?

Warden MCP provides an MCP server that bridges AI agents with Vaultwarden/Bitwarden vaults. It proxies requests from agents to the Bitwarden CLI (bw), allowing secure search, read, creation, update, move, and deletion of vault items while keeping cryptographic handling inside the official CLI.

How to use Warden MCP?

1. Install – the server runs directly via npx:

   npx -y @icoretech/warden-mcp@latest --stdio
   

2. Provide credentials via environment variables (or HTTP headers in shared‑service mode):
   • BW_HOST – URL of the Vaultwarden/Bitwarden instance
   • BW_CLIENTID / BW_CLIENTSECRET or BW_USER / BW_PASSWORD
   • optional KEYCHAIN_ALLOW_ENV_FALLBACK=true for single‑tenant HTTP mode
3. Connect from an MCP client using either the stdio endpoint (--stdio) or the HTTP/SSE endpoint (http://localhost:3005/sse?v=2).
4. Invoke tools such as keychain_get_password, keychain_create_login, keychain_search_items, etc., as defined in the tool reference.

Key features of Warden MCP

• Full Bitwarden API support via the official CLI (search, read, write, folder/collection management, attachments, sends).
• Multiple deployment modes – stdio for single‑agent use, streamable HTTP/SSE for shared services.
• Secure defaults – secrets are redacted unless reveal:true is explicitly requested; optional read‑only and no‑reveal modes.
• Per‑profile state isolation under KEYCHAIN_BW_HOME_ROOT.
• Docker image available (ghcr.io/icoretech/warden-mcp) with non‑root user and persistent volume support.
• Metrics and health checks (/healthz, /metricsz).
• Extensible tool namespace via TOOL_PREFIX and TOOL_SEPARATOR.

Use cases of Warden MCP

• Agent‑driven login automation – fetch credentials and TOTP codes during browser‑based workflows.
• Secure secret management for CI/CD – scripts can retrieve vault items without embedding passwords.
• Multi‑tenant credential service – a single HTTP server can serve several agents, each providing its own X‑BW‑* headers.
• Vault administration via AI – create or update items, manage folders, organizations, and collections programmatically.
• Compliance‑focused automation – read‑only mode for audit tooling, no‑reveal mode for untrusted contexts.

FAQ from the Warden MCP

Q: Do I need to install the Bitwarden CLI separately? A: No. The server bundles a vetted @bitwarden/cli version. You can also point BW_BIN to a custom binary or install it globally.

Q: How are credentials protected in HTTP mode? A: They travel in custom X‑BW‑* headers; you should bind the server to localhost, use TLS, or place it behind an authenticated reverse proxy.

Q: Can I run the server in a Docker container? A: Yes. Use the official image:

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

Q: What if I need read‑only access only? A: Set READONLY=true or KEYCHAIN_READONLY=true to hide mutating tools and reject write calls.

Q: How do I disable secret revelation? A: Enable NOREVEAL=true or KEYCHAIN_NOREVEAL=true; all tools will return redacted values unless the client explicitly overrides.

Q: Is there a way to limit memory usage? A: Adjust KEYCHAIN_MAX_HEAP_USED_MB; set to 0 to disable the fuse.

Q: Where are the per‑profile Bitwarden states stored? A: Under ${HOME}/bw‑profiles by default (KEYCHAIN_BW_HOME_ROOT). Secure this directory.

Q: Are there any known limitations? A: Search does not cover custom field values; SSH keys are stored as secure notes; export/import features are intentionally omitted.

Q: How can I contribute? A: Run npm run lint and appropriate test commands, then open a PR. See CONTRIBUTING.md for details.

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:

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:

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:

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:

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 22.x and npm 10.x 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 dependency
3. system bw from PATH

The bundled @bitwarden/cli version is currently 2026.8.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 bw is missing, install the CLI explicitly or point BW_BIN to a known binary:

npm install -g @bitwarden/cli@2026.8.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

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:

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:

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