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

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:

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