bws-secret-delivery-mcp

A deliberately narrow Model Context Protocol server for Bitwarden Secrets Manager. It uses Bitwarden's official bws CLI to resolve secrets and deliver them directly to approved local files without returning secret values to the MCP client or model.

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

Why this exists

General-purpose Bitwarden/BWS MCP servers are useful when an agent genuinely needs to see or manage secrets. Infrastructure automation often needs a different boundary: the agent should be able to say which secret goes to which approved consumer file without receiving the secret itself.

bws-secret-delivery-mcp intentionally does less:

• metadata-only project and secret discovery;

• direct secret-to-file delivery;

• complete raw env-file generation from selected secrets;

• no plaintext secret retrieval;

• no arbitrary command execution;

• no creation, editing or deletion of Bitwarden secrets or projects.

Related MCP server: VaultBridge

Tool surface

There is intentionally no get_secret, run, create, edit, or delete tool.

Requirements

• Python 3.12+

• Bitwarden Secrets Manager CLI (bws)

• A dedicated Bitwarden Machine Account with access only to the projects the MCP server needs

• An MCP client that supports stdio servers

Install bws using Bitwarden's official installation instructions.

Configuration

The server is configured with environment variables supplied by the MCP host:

Example MCP registration:

{
  "mcpServers": {
    "bws-secret-delivery": {
      "command": "uv",
      "args": [
        "run",
        "--frozen",
        "--directory",
        "/opt/bws-secret-delivery-mcp",
        "bws-secret-delivery-mcp"
      ],
      "env": {
        "BWS_ACCESS_TOKEN_FILE": "/run/secrets/bws-machine-token",
        "BWS_ALLOWED_OUTPUT_DIRS": "/srv/app-a/.secrets:/srv/app-b/.secrets"
      }
    }
  }
}

Keep allowed output roots narrow. A dedicated consumer secret directory is safer than allowing an entire application or stack tree.

Raw env files

bws_secret_write_raw_env_file writes one complete file in deterministic key order. Values are emitted exactly after KEY=. Values containing NUL, LF or CR are rejected because the format is intentionally line-oriented.

For Docker Compose 2.30+ use the file with format: raw so Compose does not interpret $, quotes or other characters in secret values:

env_file:
  - path: ./.secrets/runtime.env
    format: raw

Example tool input:

{
  "target_path": "/srv/my-app/.secrets/runtime.env",
  "secrets": {
    "DATABASE_PASSWORD": "database-password",
    "API_TOKEN": "2e71f52b-0000-0000-0000-000000000000"
  }
}

Each mapping value is either an exact Bitwarden secret key or a secret UUID. If a key is ambiguous, supply project_id or use a UUID.

File-safety behavior

• target_path must be absolute.

• Its resolved parent must remain inside a configured output root.

• Existing symlinks and non-regular target files are rejected.

• Existing targets with permissions for other are rejected.

• Writes use a temporary file in the same directory, fsync, atomic os.replace(), then a parent-directory fsync.

• Existing mode and ownership are preserved when possible.

• MCP responses contain target metadata and secret identifiers, never secret values or value lengths.

Development

python -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
pytest

Scope

This server is for interactive/operator-driven secret delivery. It is not intended to replace declarative secret renderers, deployment orchestration, Kubernetes secret operators, or a full Bitwarden administration client.

License

MIT