Which integrations are available for this server?

Manages Bitwarden organization vaults with ACID transactions, WAL logging, and human-in-the-loop approval for mutations while keeping secrets blind from AI agents.

How do I use bw-proxy?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@bw-proxy list items in the 'Engineering' collection" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

bw-proxy

by KpihX

Overview Schema Source Related Servers Discussions Admin

Python

Local

🔐 BW-Proxy — Sovereign Bitwarden Appliance

Zero Trust · AI-Blind · ACID Durable
The authoritative appliance for Bitwarden organization vault control. Keep AI agents and LLMs blind to your real secrets while giving them full auditing and refactoring powers.

🏛️ Project Architecture (Sovereign Tree)

BW-PROXY PROJECT
├── 📂 src/bw_proxy/     ◄── Core Engine (ACID Transaction, WAL, Redaction)
├── 📂 scripts/          ◄── Host-side Shims (Dynamic porting, Browser HITL)
├── 📂 docs/             ◄── Deep-dive Hardening & Operator Guides
├── 📄 install.sh        ◄── System-wide Appliance Installer (Root-owned)
├── 📄 Makefile          ◄── Developer & Release Automator
└── 📄 Dockerfile        ◄── Multi-stage Hardened Runtime

Related MCP server: stillvault-mcp

🚀 Installation Modes

A. Appliance Mode (Standard Pro)

Ideal for production use. Installs a root-owned binary and uses the official image.

Via curl (Zero-Clone):

curl -fsSL https://raw.githubusercontent.com/KpihX/bw-proxy/main/install.sh | sudo bash

What it does internally:

Image: Pulls ghcr.io/kpihx/bw-proxy:latest.
Binary: Creates /usr/local/bin/bw-proxy (owned by root).
Config: Creates /etc/bw-proxy/.
Data: Creates a persistent Docker volume bw_mcp_bw-data.

B. Developer Mode (Source Clone)

Ideal for contribution or source-level auditing.

git clone https://github.com/KpihX/bw-proxy.git
cd bw-proxy
make docker-install  # Requires SUDO for builds

⚙️ Core Mechanisms (The Magic)

1. The HITL Browser Flux

When an AI agent requests a vault change, the proxy intercepts the execution:

Port Allocation: The host shim finds a free random port.
Container Launch: The appliance starts, mapping the internal HITL server to that port.
URL Interception: The shim detects the Approval URL in stdout and automatically opens your browser.
Human Approval: You review the rationale and the diff, then approve with your Master Password.

2. The 3-Phase ACID Commit (WAL)

Every mutation is transactional.

Simulation: Actions are validated in RAM first.
WAL: Actions are encrypted and logged to disk before execution.
Commit: Actions are sent to the Bitwarden CLI.
Rollback: If a crash occurs, the proxy performs a LIFO rollback on the next start.

3. Scoped Union Fetch

To handle organizational vaults without metadata loss:

The proxy discovers all accessible Organizations and Collections first.
It then performs scoped queries (--organizationid) to fetch "rich" items with full metadata.
It merges results with the global vault list, ensuring organizational assignments are preserved.

🕹️ Interface Modes

1. CLI Mode (Recommended for Humans & AI Agents) 🚀

The CLI is the most efficient and agnostic way to interact with the appliance. It uses RPC 2.0 (JSON), supports exact examples, and provides rich help documentation.

For AI Agents: Using the CLI via run_command is more token-efficient than MCP and offers greater flexibility.

bw-proxy admin status   # Health check
bw-proxy admin unlock   # Create a 5-minute session lease
bw-proxy do list-items  # Quick redacted scan

TIP

AI Integration: To enable full AI recognition of these commands, copy the .agents/skills/bw-proxy directory to your global ~/.agents/skills/ or into a project-specific .agents/skills/ directory.

2. MCP Mode (Standard Stdio)

Start the stdio server for standard MCP clients like Gemini, Claude, or Cursor.

bw-proxy mcp serve

🛠️ Maintenance & Release

Update: curl ... | sudo bash (re-runs the installer).
Uninstall: sudo ./uninstall.sh.
Release (Dev): make release (automatic tagging and GHCR propulsion).

⚖️ License

MIT License. See LICENSE for details.

Designed with ❤️ by KpihX.

Available Tools

10 tools

compare_secrets_batchD

ParametersJSON Schema

Name	Required	Description	Default
`payload`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_all_vault_duplicatesD

ParametersJSON Schema

Name	Required	Description	Default
`payload`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_duplicates_batchD

ParametersJSON Schema

Name	Required	Description	Default
`payload`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_item_duplicatesD

ParametersJSON Schema

Name	Required	Description	Default
`payload`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_proxy_audit_contextD

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_templateD

ParametersJSON Schema

Name	Required	Description	Default
`template_type`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_vault_mapD

ParametersJSON Schema

Name	Required	Default
`folder_id`	No
`trash_state`	No	all
`include_orgs`	No
`search_items`	No
`collection_id`	No
`search_folders`	No
`organization_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

inspect_transaction_logD

ParametersJSON Schema

Name	Required	Description	Default
`n`	No
`tx_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

propose_vault_transactionD

ParametersJSON Schema

Name	Required	Description	Default
`rationale`	Yes
`operations`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

refactor_item_secretsD

ParametersJSON Schema

Name	Required	Description	Default
`rationale`	Yes
`operations`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

10 tool updatesv3.6.3Jul 13, 2026
- First observedcompare_secrets_batch
- First observedfind_all_vault_duplicates
- First observedfind_duplicates_batch
- First observedfind_item_duplicates
- First observedget_proxy_audit_context
- First observedget_template
- First observedget_vault_map
- First observedinspect_transaction_log
- First observedpropose_vault_transaction
- First observedrefactor_item_secrets

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

D1.5/5.0

Scored 2026-07-13 13:30 across 10 tools

Disambiguation2/5

Multiple tools focus on finding duplicates (find_all_vault_duplicates, find_duplicates_batch, find_item_duplicates) with unclear scope distinctions. Without descriptions, an agent would likely struggle to choose between them.

Naming Consistency2/5

Naming patterns are inconsistent: some start with 'find', some with 'get', others with different verbs (compare, inspect, propose, refactor). The placement of 'batch' varies, and there is no consistent verb_noun structure.

Tool Count4/5

10 tools is a reasonable count for a specialized secret management proxy. It covers a variety of operations without being excessive, though some categories are overrepresented.

Completeness2/5

The tool set lacks basic CRUD operations (create, read, update, delete) for items or vaults. Advanced operations like proposing transactions and refactoring are present, but foundational actions are missing, leaving significant gaps.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

agentlock
io.github.Olum289
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Security Agent Orchestration
2
IdentArk Gateway
io.identark
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
Security Agent Orchestration
29
FullmaktOAuth
ai.fullmakt
Credential broker for AI agents: scoped, revocable API access with policy enforcement and audit.
Security Autonomous Agents Agent Orchestration
1
agentdevx C
io.github.mirajmahmudul
Give your AI hands. Identity, credential vault, and API gateway for autonomous agents.
Agent Orchestration Developer Tools
382

Related MCP Servers

MCP Vaultwarden Server
Security App Automation Developer Tools
fkom13
A
license
Not graded
quality
D
maintenance
Enables AI agents and automation scripts to securely interact with self-hosted Vaultwarden instances through the Bitwarden CLI, automatically managing vault sessions and providing tools to read, create, update, and delete secrets programmatically.
Updated 10 months ago (2025-11-15 21:43 UTC)
6 npm
1
MIT
stillvault-mcp
Security Shell Access
Wolstapp
A
license
A
quality
D
maintenance
Enables AI agents to securely use real secrets (API keys, database passwords) by requiring human approval for each release, ensuring secrets never enter the model's context.
Updated 3 months ago (2026-06-19 12:26 UTC)
2
Apache 2.0
agentkeychain
Security Autonomous Agents
linsipeng
A
license
Not graded
quality
A
maintenance
Provides a zero-knowledge credential vault for AI agents, allowing secure storage, retrieval, and management of secrets with cross-agent delegation and tamper-evident audit.
Updated 11 days ago (2026-09-04 02:35 UTC)
MIT
brain-mcp
Note Taking Knowledge & Memory File Systems
kaeldominion
A
license
Not graded
quality
B
maintenance
Enables AI agents to securely read and write to an Obsidian-compatible Markdown vault with per-agent access control, audit logging, and conflict resolution.
Updated 2 months ago (2026-07-27 09:06 UTC)
Apache 2.0