bws-secret-delivery-mcp

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 select a credential profile and 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;
• one or more named Machine Account credential profiles;
• optional expected-project scope checks per profile;
• direct secret-to-file delivery;
• complete raw env-file generation from selected secrets;
• per-profile output-directory allowlists;
• no plaintext secret retrieval;
• no arbitrary command execution;
• no creation, editing or deletion of Bitwarden secrets or projects.

Tool surface

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

Every tool accepts an optional profile. Read tools query every configured profile when it is omitted. Write tools require an explicit profile whenever more than one profile is configured.

Requirements

• Python 3.12+
• Bitwarden Secrets Manager CLI (bws)
• Dedicated Bitwarden Machine Account access tokens with only the required project access
• An MCP client that supports stdio servers

Install bws using Bitwarden's official installation instructions.

Configuration

Named profiles

For central administrative control planes, set BWS_PROFILES_FILE to an absolute path containing non-secret JSON configuration. Machine Account tokens remain in separate private files.

{
  "profiles": {
    "app-a": {
      "access_token_file": "/run/secrets/app-a-bws-token",
      "server_url": "https://vault.bitwarden.eu",
      "expected_project_names": ["App A Runtime"],
      "allowed_output_directories": ["/srv/app-a/.secrets"]
    },
    "metadata-only": {
      "access_token_file": "/run/secrets/metadata-bws-token",
      "server_url": "https://vault.bitwarden.eu",
      "expected_project_names": ["Metadata Runtime"]
    }
  }
}

Profile fields:

Global environment variables:

Example MCP registration:

{
  "mcpServers": {
    "bws-secret-delivery": {
      "command": "uv",
      "args": [
        "run",
        "--frozen",
        "--directory",
        "/opt/bws-secret-delivery-mcp",
        "bws-secret-delivery-mcp"
      ],
      "env": {
        "BWS_PROFILES_FILE": "/etc/bws-secret-delivery/profiles.json",
        "BWS_BIN": "/usr/local/bin/bws"
      }
    }
  }
}

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

Legacy single-profile mode

Version 0.2 retains the original environment-only configuration for simple deployments:

Do not set BWS_ACCESS_TOKEN_FILE together with BWS_PROFILES_FILE.

Project-scope guard

If expected_project_names is configured, secret discovery and delivery first verify that the Machine Account can see exactly that project-name set. This makes accidental future privilege expansion fail closed instead of silently broadening the MCP's authority.

bws_project_list remains available to inspect accessible project metadata when diagnosing a scope mismatch.

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 in multi-profile mode:

{
  "profile": "app-a",
  "target_path": "/srv/app-a/.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 within a profile, supply project_id or use a UUID.

File-safety behavior

• Token files and the profiles file must be regular non-symlink files.
• Token files must grant no group or other permissions.
• target_path must be absolute.
• Its resolved parent must remain inside the selected profile's configured output roots.
• 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 profile, target and secret metadata, never secret values or value lengths.
• Provider stdout from secret operations and provider stderr from failures are never echoed into MCP errors.

Development

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

Scope

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

License

MIT