Bitwarden Agent Vault

An unofficial, open-source Codex plugin and local MCP server for using Bitwarden Secrets Manager as durable credential storage for agent workflows.

The server runs locally over MCP stdio. It does not open a network port and it does not contain a Bitwarden token, organization ID, project ID, password, or API key. Every installation must supply its own Bitwarden machine account and private configuration.

This community project is not affiliated with or endorsed by Bitwarden, Inc.

What it does

• Stores and rotates stable agent credentials in Bitwarden Secrets Manager.
• Lists projects and secret metadata without returning values.
• Retrieves a secret when plaintext is explicitly required.
• Injects selected secrets into an allowlisted executable without placing them in the normal command output.
• Opens the Bitwarden Secrets Manager web vault on macOS.
• Includes a Codex skill for automatically saving durable credentials that Codex creates, receives, or discovers.

Security model

Codex MCP client
    | local JSON-RPC over stdin/stdout
    v
Bitwarden Agent Vault MCP server
    | machine token from macOS Keychain or BWS_ACCESS_TOKEN
    v
Bitwarden Secrets Manager API via bws

• The MCP server uses stdio and has no HTTP listener.
• The machine token is read from macOS Keychain by default. On other platforms, it must be supplied to the MCP process as BWS_ACCESS_TOKEN.
• Bitwarden project and secret permissions remain the authoritative access boundary. Use a least-privilege machine account.
• store_secret refuses to overwrite an existing key unless overwrite: true is explicitly supplied.
• get_secret is disabled by default and requires an explicit private allowPlaintextReveal opt-in.
• run_with_secrets is disabled by default. When enabled, it requires an absolute executable allowlist and injects only the requested secret keys.
• Command output is redacted for exact secret values. Redaction cannot prevent an executable from encoding, transforming, writing, or transmitting a secret. Only allowlist purpose-built programs you trust.
• get_secret intentionally returns plaintext to the MCP client. Do not expose this server to untrusted clients or untrusted prompt sources.

See SECURITY.md for reporting and operational guidance.

Requirements

• Node.js 20 or later
• A Bitwarden Secrets Manager organization, project, and machine account
• Bitwarden Secrets Manager CLI (bws)
• Codex with local plugin/MCP support
• macOS for the included Keychain helper; Linux can use an MCP-process environment variable

The server may work on Windows when bws is installed and BWS_ACCESS_TOKEN is provided, but the helper scripts are currently tested for macOS and Linux shells only.

Install

Clone the repository into the conventional personal plugin source location:

git clone https://github.com/ceweldy/bitwarden-agent-vault-mcp.git \
  "$HOME/plugins/bitwarden-agent-vault"
cd "$HOME/plugins/bitwarden-agent-vault"
npm ci

Install bws with the checksum-verifying helper, or install it from Bitwarden's official release process:

./scripts/install-bws.sh

Create a Bitwarden Secrets Manager project and a machine account with only the required project permissions. Copy the machine access token once.

On macOS, store the token in Keychain without placing it in a file or shell history:

./scripts/store-machine-token.sh

On non-macOS systems, configure BWS_ACCESS_TOKEN only in the MCP host's private process environment. Do not commit it or place it in a shared shell profile.

Create the private configuration:

mkdir -p "$HOME/.config/bitwarden-agent-vault"
cp config.example.json "$HOME/.config/bitwarden-agent-vault/config.json"
chmod 600 "$HOME/.config/bitwarden-agent-vault/config.json"

Replace defaultProjectId with your Bitwarden project UUID. The UUID is not a secret, but keeping deployment metadata outside the repository avoids leaking your vault structure.

Check the live connection:

./scripts/doctor.sh

Add the Codex plugin

Add this entry to the plugins array in your personal Codex marketplace at ~/.agents/plugins/marketplace.json. Preserve any entries already in that file.

{
  "name": "bitwarden-agent-vault",
  "source": {
    "source": "local",
    "path": "./plugins/bitwarden-agent-vault"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

Then install it:

codex plugin add bitwarden-agent-vault@personal

Start a new Codex task so the MCP tools and skill are loaded.

Configuration

The server reads ~/.config/bitwarden-agent-vault/config.json unless BITWARDEN_AGENT_CONFIG points to another file.

Field	Required	Meaning
serverUrl	No	Bitwarden API server; defaults to Bitwarden cloud.
defaultProjectId	Recommended	Project used when a tool call omits project_id.
allowPlaintextReveal	No	Must be exactly true to enable get_secret.
allowCommandExecution	No	Must be exactly true to enable run_with_secrets.
allowedExecutables	When enabled	Absolute paths to trusted executable files.

To opt into command execution, use a private configuration such as:

{
  "serverUrl": "https://vault.bitwarden.com",
  "defaultProjectId": "replace-with-your-bitwarden-project-id",
  "allowPlaintextReveal": false,
  "allowCommandExecution": true,
  "allowedExecutables": [
    "/absolute/path/to/a-purpose-built-tool"
  ]
}

Avoid allowlisting shells, general-purpose interpreters, download tools, or network clients. They defeat the purpose of an executable allowlist.

MCP tools

Tool	Behavior
status	Checks local token, CLI, optional remote access, and command-execution state.
list_projects	Returns accessible project metadata.
list_secrets	Returns secret names and metadata, never values.
get_secret	Returns one exact secret value when privately enabled.
store_secret	Creates a secret or explicitly rotates an exact-key match.
run_with_secrets	Runs an enabled, allowlisted executable with selected secret keys.
open_bitwarden	Opens the Bitwarden Secrets Manager web UI on macOS.

Development

npm ci
npm run check
npm audit --omit=dev

Tests use a fake bws fixture and contain no real credentials. Never add live tokens, vault exports, .env files, personal configuration, or customer data to tests or issue reports.

License

MIT