vaultwarden-drop-slot-mcp

# vaultwarden-drop-slot-mcp

**MCP server, CLI and Node.js module for write-only credential deposits into a
self-hosted Vaultwarden (Bitwarden-compatible) vault.** AI agents such as Claude
Code and Codex, and deployment scripts, can save new logins (passwords) and secure
notes, encrypted with age before they reach the inbox, without a vault login that
can read existing secrets.

[![Verify](https://github.com/ip2k/vaultwarden-drop-slot-mcp/actions/workflows/verify.yml/badge.svg)](https://github.com/ip2k/vaultwarden-drop-slot-mcp/actions/workflows/verify.yml)

## TL;DR

**Let an agent save a new password without giving it the keys to your vault.**

An agent or deployment script creates a credential. You want it saved in
Vaultwarden without pasting it into chat, copying it by hand, or giving that
agent a vault login that can read existing passwords. This project provides a
**deposit-only path**: encrypt the new item, hand it to an inbox, and receive a
receipt. A separate trusted importer saves it as an ordinary login or secure
note that you open with your existing Bitwarden clients.

- **For agents:** two MCP tools — deposit a secret and check its delivery status.
- **For scripts:** a stdin-based CLI and a typed Node.js module.
- **For operators:** portable Docker containers, your own Vaultwarden, and a
  dedicated importer account. No changes to Vaultwarden are required.

**The restriction applies to the producer.** The importer has vault access;
keep its account and host private. Secrets included in AI tool arguments can
still be seen by the AI provider. Use the CLI or Node module directly when a
script can generate and deposit a secret without involving the model.

**Release 0.1.0.** Install from npm (`npm install vaultwarden-drop-slot-mcp`,
or run `npx -y vaultwarden-drop-slot-mcp`), from this repository, or from a
locally packed tarball. The MCP server is also listed in the
[MCP Registry](https://registry.modelcontextprotocol.io) as
`io.github.ip2k/vaultwarden-drop-slot-mcp`. Containers are built locally. Original code is Apache-2.0. This is an independent project,
not affiliated with Bitwarden or Vaultwarden. See the
[verification record](docs/VERIFICATION.md) for tested behavior and limits.

**Start here:** [Setup walkthrough](docs/SETUP.md) ·
[MCP connections](docs/MCP-CONNECTIONS.md) · [Operations](docs/OPERATIONS.md) ·
[Security design](docs/THREAT-MODEL.md)

## From a new credential to your vault

```mermaid
flowchart TB
    producer["Agent or deployment script"]
    client["Local MCP, CLI or Node client<br/>Encrypt with pinned age public key"]
    inbox["HTTPS inbox<br/>Store ciphertext and receipt state"]
    importer["Private importer<br/>Decrypt with age private key"]
    vault["Vaultwarden<br/>Dedicated organization and collection"]
    owner["You<br/>Existing Bitwarden clients"]
    producer -->|New login or secure note| client
    client -->|Ciphertext plus writer authentication| inbox
    importer -->|Claim encrypted job| inbox
    inbox -->|Ciphertext job| importer
    importer -->|Create and privately verify| vault
    vault -->|Normal vault sync| owner
    importer -.->|Verified delivery acknowledgment| inbox
    inbox -.->|Opaque receipt and status only| client
    classDef publicSide fill:#e8f1ff,stroke:#315f99,color:#122842
    classDef privateSide fill:#e7f4ec,stroke:#36704a,color:#173422
    class producer,client,inbox publicSide
    class importer,vault,owner privateSide
```

The inbox cannot decrypt the payload. Only the private importer holds the age
identity and the dedicated Bitwarden CLI session. The public API has no vault
read, search, list, edit, or delete operations. Item URLs are stored as text;
the service never fetches them.

## How it fits together

| Component | Has | Can do |
| --- | --- | --- |
| Local MCP / CLI / Node client | Writer token, pinned public recipient | Encrypt, deposit, check own receipts |
| HTTPS inbox | Token hashes, encrypted queue | Authenticate, queue, return delivery states |
| Private importer | age private key, dedicated vault session | Decrypt and create; privately read to verify delivery |
| Optional remote MCP adapter | OAuth configuration, writer credentials | Authenticate users, encrypt plaintext tool arguments, forward deposits |

The **writer capability is create-only**. The importer is trusted and can read
everything its account can access. Use a dedicated automation account and a
separate organization shared with your normal account. A folder or collection is
not an independent cryptographic boundary. Personal-vault mode requires an
explicit configuration opt-in.

An HTTP MCP adapter sees plaintext, as does an AI provider receiving those tool
arguments. For secrets generated by a deployment script, pipe directly into the
local CLI or call the Node module. No arbitrary file-path, URL-fetch, shell, read,
search, edit, or delete tools exist.

## Setup overview

Follow the [complete setup walkthrough](docs/SETUP.md) for copyable commands,
file permissions, TLS, owner login, routing and a first test. It assumes a
Linux Docker host with Compose v2 and an existing HTTPS Vaultwarden instance;
the local client/module needs Node.js **24.2+**. Image builds support amd64 and
arm64; execution has been verified on amd64.

1. **Build from source.** Clone this repository, run `npm ci --ignore-scripts`,
   `npm test`, and `npm run build`. Build the default runtime and optional importer
   images. The default image contains no Bitwarden CLI.
2. **Create a private deployment directory.** Generate enrollment material and
   split producer, inbox and importer files. Keep it outside the checkout.
3. **Configure TLS and start the inbox.** Use certificates trusted by the clients
   and importer. Publish only the HTTPS intake port; the worker port stays private.
4. **Enroll a dedicated vault account.** Create an organization and collection,
   invite the importer as a User, accept and confirm membership, and explicitly
   grant collection edit access. Log in from your private terminal.
5. **Set the destination and start the importer.** Map the writer ID to the
   organization and collection UUIDs in private configuration.
6. **Test, then connect MCP.** Deposit a synthetic item, wait for `imported`, and
   open it in your normal Bitwarden client. Then follow the
   [client-specific MCP instructions](docs/MCP-CONNECTIONS.md).

```sh
git clone https://github.com/ip2k/vaultwarden-drop-slot-mcp.git
cd vaultwarden-drop-slot-mcp
npm ci --ignore-scripts
npm test
npm run build
node dist/cli.js --help
```

For a Node application, `npm install vaultwarden-drop-slot-mcp`. To use a
local build instead, run `npm pack` here and install the resulting `.tgz` with
`npm install /absolute/path/vaultwarden-drop-slot-mcp-0.1.0.tgz`.

## What a receipt means

```mermaid
sequenceDiagram
    participant P as Producer
    participant I as Encrypted inbox
    participant W as Private importer
    participant V as Vaultwarden
    P->>I: Encrypted item and request UUID
    I-->>P: Opaque receipt (queued)
    W->>I: Claim job
    I-->>W: Ciphertext (importing)
    Note over W: Decrypt, check destination, record intent
    W->>V: Create item with private submission marker
    W->>V: Verify marker in the selected destination
    V-->>W: Matching item
    W->>I: Acknowledge verified import
    Note over I: Delete queued ciphertext and retain receipt
    P->>I: Check own receipt
    I-->>P: imported
    Note over P,I: Same UUID means same ciphertext<br/>and the same receipt
```

`queued` means accepted by the inbox; `imported` means privately verified in the
vault. A locked importer leaves work queued. Failures and ambiguous creates use
bounded retries and private reconciliation; see [delivery limits](#delivery-and-operational-limits).

## Local MCP

After completing setup, configure your MCP client to launch the executable with
a private producer config file. Use absolute paths; the paths below are examples.
See [MCP connections](docs/MCP-CONNECTIONS.md) for Claude Code, Codex, desktop
clients, Docker stdio and remote HTTP instructions:

```json
{
  "mcpServers": {
    "vaultwarden-drop-slot": {
      "command": "node",
      "args": ["/absolute/path/to/dist/cli.js", "stdio", "/private/path/client.json"]
    }
  }
}
```

Exactly two tools are available:

- `deposit_secret({request_id, payload})`: queue a new login or secure note.
- `deposit_status({receipt})`: return `queued`, `importing`, `imported`, or `failed`.

Use a fresh UUID for each new item. Reuse it only to retry the **original** item.
The client retains the original encrypted envelope in its private spool; changed
arguments with the same request ID do not create or overwrite anything. Retrying
after a timeout therefore uses exactly the same ciphertext. Keep the spool until
retries are no longer needed; it is bounded at 10,000 entries.

Tools return receipts only. Keep tokens in host configuration; never put them in
prompts, tool arguments, or checked-in MCP settings.

## CLI and Node module

The `deposit` command reads `{request_id,payload}` JSON from stdin. A secret
generator can pipe to it without putting the secret in shell arguments or a file:

```sh
your-secret-generator | node dist/cli.js deposit /private/path/client.json
node dist/cli.js status /private/path/client.json RECEIPT_UUID
```

The npm module exports a typed `DepositClient`, `seal`, `fingerprint`, validation
schemas, and protocol types. Example inside your own deployment program:

```ts
import { DepositClient } from 'vaultwarden-drop-slot-mcp';

const client = new DepositClient(enrolledClientConfig);
const receipt = await client.deposit(persistedRequestId, {
  type: 'login',
  name: 'New service',
  username: generatedUsername,
  password: generatedPassword,
  urls: ['https://service.example.com'],
});
// Only the receipt is safe to log.
console.log(receipt);
```

`prepare()` writes a ciphertext-only spool entry; `submit()` sends that exact
envelope. These are avail