@icoretech/warden-mcp 0.2.28 → 0.2.30
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +291 -491
- package/dist/bw/bwSession.js +79 -6
- package/package.json +8 -8
package/README.md
CHANGED
|
@@ -1,233 +1,97 @@
|
|
|
1
1
|
# warden-mcp
|
|
2
2
|
|
|
3
|
+
**Vaultwarden / Bitwarden MCP server for credential-aware AI agents.**
|
|
4
|
+
|
|
3
5
|
[](https://www.npmjs.com/package/@icoretech/warden-mcp)
|
|
4
|
-
[](https://ghcr.io/icoretech/warden-mcp)
|
|
5
6
|
[](https://github.com/icoretech/warden-mcp/actions/workflows/ci.yml)
|
|
6
7
|
[](LICENSE)
|
|
8
|
+
[](package.json)
|
|
9
|
+
[](https://ghcr.io/icoretech/warden-mcp)
|
|
7
10
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
## Highlights
|
|
15
|
-
|
|
16
|
-
- MCP Streamable HTTP endpoint at `/sse` (GET/POST; DELETE intentionally unsupported) + health check at `GET /healthz`
|
|
17
|
-
- Runtime guardrail metrics at `GET /metricsz`
|
|
18
|
-
- Item types: **login**, **secure note**, **card**, **identity**, plus an **SSH key** convention (secure note + standard fields)
|
|
19
|
-
- Attachments: create/delete/download
|
|
20
|
-
- Organization + collection helpers (list + org-collection CRUD)
|
|
21
|
-
- Safe-by-default: item reads are **redacted** unless explicitly revealed; secret helper tools return `null` unless `reveal: true`
|
|
22
|
-
- Strong fit for LLM automation: pair it with a browser-capable MCP host so an agent can fetch credentials, complete sign-in flows, read TOTP codes, and keep automating after login
|
|
23
|
-
|
|
24
|
-
## Text-Only MCP Client Behavior
|
|
25
|
-
|
|
26
|
-
Some MCP hosts, including agent shells that optimize tool output for the model,
|
|
27
|
-
only forward `content[]` text blocks and do not expose `structuredContent` to
|
|
28
|
-
the agent. `warden-mcp` therefore mirrors the non-secret identifiers needed for
|
|
29
|
-
follow-up calls into visible text by default.
|
|
30
|
-
|
|
31
|
-
For search/list tools, the text output includes concise rows with stable ids and
|
|
32
|
-
safe metadata such as names, item type, username, URI values, organization id,
|
|
33
|
-
folder id, and collection ids. Secret fields are not included in those summaries.
|
|
34
|
-
Create/update/move/restore helpers that return a folder, collection, or item use
|
|
35
|
-
concise visible summaries with reusable ids plus safe item metadata, including
|
|
36
|
-
nested login username/URI values and attachment metadata where present. Delete
|
|
37
|
-
helpers include the requested ids when no object is returned.
|
|
38
|
-
|
|
39
|
-
For scalar helper tools, the text output follows the reveal contract:
|
|
40
|
-
|
|
41
|
-
- `encode`, `get_uri`, and `get_exposed` show their returned scalar value
|
|
42
|
-
- `get_username` shows the username because Bitwarden treats it as non-secret
|
|
43
|
-
- `get_password`, `get_totp`, and `get_notes` show `not revealed` unless you pass
|
|
44
|
-
`reveal: true`
|
|
45
|
-
- `generate` and `generate_username` follow the same reveal contract: they show
|
|
46
|
-
`generated: not revealed` by default and the generated value only with
|
|
47
|
-
`reveal: true`
|
|
48
|
-
- `get_password_history` shows `not revealed` unless you pass `reveal: true`
|
|
49
|
-
- Send helpers mirror their returned Send payloads into visible text so
|
|
50
|
-
text-only clients can use created Send links, fetched Send metadata, received
|
|
51
|
-
text, and file-download metadata without reading `structuredContent`
|
|
52
|
-
- if `NOREVEAL=true` or `KEYCHAIN_NOREVEAL=true`, revealed values are still
|
|
53
|
-
suppressed server-side
|
|
54
|
-
|
|
55
|
-
When a lookup term matches multiple login items, `keychain_get_username` and
|
|
56
|
-
revealed `keychain_get_password` return an `AMBIGUOUS_LOOKUP` error with visible
|
|
57
|
-
candidate ids. Retry with `term` set to an exact candidate `id`, or call
|
|
58
|
-
`get_item` with that `id`.
|
|
59
|
-
|
|
60
|
-
If `KEYCHAIN_TEXT_COMPAT_MODE=structured_json` is enabled, supported success and
|
|
61
|
-
ambiguity/error results mirror their `structuredContent` into the visible text as
|
|
62
|
-
serialized JSON instead of the human summaries.
|
|
63
|
-
|
|
64
|
-
## LLM Automation Use Case
|
|
65
|
-
|
|
66
|
-
`warden-mcp` is not only useful for vault administration. A very practical use case is pairing it with an LLM that can also drive a browser.
|
|
67
|
-
|
|
68
|
-
That lets the agent do end-to-end authenticated workflows such as:
|
|
69
|
-
|
|
70
|
-
- open a site or backoffice in the browser
|
|
71
|
-
- read the right login from Vaultwarden or Bitwarden
|
|
72
|
-
- fill username and password without hardcoding secrets in prompts or config
|
|
73
|
-
- retrieve a current TOTP code with `keychain_get_totp` for TOTP-based MFA
|
|
74
|
-
- continue the real task after login, such as navigation, data entry, exports, or routine admin work
|
|
75
|
-
|
|
76
|
-
In practice, this is what makes the server useful for full automation, not just secret lookup. The same MCP session that gives the model browser control can also give it scoped access to the credentials and MFA material needed to finish the workflow.
|
|
77
|
-
|
|
78
|
-
## Runtime Requirement
|
|
79
|
-
|
|
80
|
-
Requires Node.js 24+ and npm when running from npm or source. The Docker image
|
|
81
|
-
already includes the supported Node runtime.
|
|
82
|
-
|
|
83
|
-
At runtime, this package shells out to the official Bitwarden CLI, `bw`.
|
|
84
|
-
|
|
85
|
-
Runtime resolution order:
|
|
86
|
-
|
|
87
|
-
- `BW_BIN` if you set it explicitly
|
|
88
|
-
- bundled `@bitwarden/cli` optional dependency if it is present
|
|
89
|
-
- system `bw` from `PATH`
|
|
90
|
-
|
|
91
|
-
That means package installation can succeed even when the optional dependency is skipped by the environment. In that case you must install `bw` separately or point `BW_BIN` to it.
|
|
92
|
-
|
|
93
|
-
Explicit fallback install:
|
|
94
|
-
|
|
95
|
-
```bash
|
|
96
|
-
npm install -g @bitwarden/cli@2026.5.0
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
Or run with an explicit binary path:
|
|
11
|
+
`warden-mcp` lets MCP clients search, create, update, move, and read
|
|
12
|
+
Vaultwarden or Bitwarden vault items through the official Bitwarden CLI (`bw`).
|
|
13
|
+
It is built for agents and automation that need credentials, TOTP codes, secure
|
|
14
|
+
notes, attachments, Sends, folders, organizations, and collections without
|
|
15
|
+
re-implementing Bitwarden client-side crypto.
|
|
100
16
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
`warden-mcp` intentionally bundles a vetted `@bitwarden/cli` version (currently
|
|
106
|
-
`2026.5.0`) instead of blindly following the newest upstream CLI on every
|
|
107
|
-
release. New `bw` releases can change login and unlock behavior in ways that
|
|
108
|
-
break automation, so `bw` upgrades should be smoke-tested against real
|
|
109
|
-
Vaultwarden flows before bumping the bundled version. Official Bitwarden
|
|
110
|
-
compatibility is intended, but it is not continuously proven in CI without a
|
|
111
|
-
real Bitwarden tenant.
|
|
112
|
-
|
|
113
|
-
This repository's compose smoke exercises both direct `bw` auth flows and the
|
|
114
|
-
MCP/SDK layers with username/password auth plus user API-key auth against a real
|
|
115
|
-
local Vaultwarden, so `@bitwarden/cli` bumps do not rely on unit coverage alone.
|
|
116
|
-
The bundled postinstall compatibility shim rewrites the affected `build/bw.js`
|
|
117
|
-
login strategies in place so the same Vaultwarden fallback can survive compatible
|
|
118
|
-
CLI bumps without a version-stamped patch artifact.
|
|
17
|
+
Use it when an agent needs to log in to real systems during a browser or admin
|
|
18
|
+
workflow, but you do not want passwords hardcoded in prompts, config files, or
|
|
19
|
+
one-off scripts.
|
|
119
20
|
|
|
120
|
-
##
|
|
121
|
-
|
|
122
|
-
### Choose a transport
|
|
21
|
+
## Quick Start
|
|
123
22
|
|
|
124
|
-
|
|
125
|
-
|
|
23
|
+
Use stdio mode when a local MCP host launches the server directly. It is the
|
|
24
|
+
simplest and most portable setup for desktop agents.
|
|
126
25
|
|
|
127
|
-
|
|
26
|
+
Prerequisites:
|
|
128
27
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
28
|
+
- Node.js 24+
|
|
29
|
+
- npm
|
|
30
|
+
- a Vaultwarden or Bitwarden account
|
|
31
|
+
- either a Bitwarden API key pair or username/password login
|
|
132
32
|
|
|
133
|
-
|
|
33
|
+
Run the server:
|
|
134
34
|
|
|
135
35
|
```bash
|
|
136
36
|
BW_HOST=https://vaultwarden.example.com \
|
|
137
|
-
|
|
37
|
+
BW_CLIENTID=user.xxxxx \
|
|
38
|
+
BW_CLIENTSECRET=xxxxx \
|
|
138
39
|
BW_PASSWORD='your-master-password' \
|
|
139
40
|
npx -y @icoretech/warden-mcp@latest --stdio
|
|
140
41
|
```
|
|
141
42
|
|
|
142
|
-
|
|
43
|
+
Username login also works:
|
|
143
44
|
|
|
144
45
|
```bash
|
|
145
46
|
BW_HOST=https://vaultwarden.example.com \
|
|
146
|
-
|
|
147
|
-
BW_CLIENTSECRET=xxxxx \
|
|
47
|
+
BW_USER=user@example.com \
|
|
148
48
|
BW_PASSWORD='your-master-password' \
|
|
149
49
|
npx -y @icoretech/warden-mcp@latest --stdio
|
|
150
50
|
```
|
|
151
51
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
Start one long-lived MCP server:
|
|
155
|
-
|
|
156
|
-
```bash
|
|
157
|
-
npx -y @icoretech/warden-mcp@latest
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
Verify it is up:
|
|
52
|
+
If the package is useful, [star the repository](https://github.com/icoretech/warden-mcp)
|
|
53
|
+
so other agent builders can find it.
|
|
161
54
|
|
|
162
|
-
|
|
163
|
-
curl -fsS http://localhost:3005/healthz
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
This mode is what makes `warden-mcp` different from a simple local wrapper:
|
|
55
|
+
## Install In MCP Hosts
|
|
167
56
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
- per-profile `bw` state is kept server-side under `KEYCHAIN_BW_HOME_ROOT`
|
|
171
|
-
- one running server can front different vault hosts or different identities without restarting
|
|
172
|
-
- it fits shared-agent and gateway setups much better than per-client local processes
|
|
57
|
+
Most local hosts should use stdio. The examples below use API-key auth; replace
|
|
58
|
+
`BW_CLIENTID` and `BW_CLIENTSECRET` with `BW_USER` if you prefer username login.
|
|
173
59
|
|
|
174
|
-
###
|
|
60
|
+
### Claude Code
|
|
175
61
|
|
|
176
62
|
```bash
|
|
177
|
-
|
|
178
|
-
-p 127.0.0.1:3005:3005 \
|
|
179
|
-
-v warden-mcp-data:/data \
|
|
180
|
-
ghcr.io/icoretech/warden-mcp:latest
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
The production image runs as the non-root `node` user (uid/gid `1000`), sets
|
|
184
|
-
`HOME=/data`, and stores Bitwarden profile state under `/data/bw-profiles` by
|
|
185
|
-
default. If you use a bind mount instead of the named volume above, make it
|
|
186
|
-
writable by uid/gid `1000`.
|
|
187
|
-
|
|
188
|
-
### Global install
|
|
189
|
-
|
|
190
|
-
```bash
|
|
191
|
-
npm install -g @icoretech/warden-mcp@latest
|
|
192
|
-
warden-mcp
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
## Connect From MCP Hosts
|
|
196
|
-
|
|
197
|
-
For local MCP hosts, stdio is the most portable option.
|
|
198
|
-
|
|
199
|
-
```bash
|
|
200
|
-
npx -y @icoretech/warden-mcp@latest --stdio
|
|
63
|
+
claude mcp add-json warden '{"command":"npx","args":["-y","@icoretech/warden-mcp@latest","--stdio"],"env":{"BW_HOST":"https://vaultwarden.example.com","BW_CLIENTID":"user.xxxxx","BW_CLIENTSECRET":"xxxxx","BW_PASSWORD":"your-master-password"}}'
|
|
201
64
|
```
|
|
202
65
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
### CLI-based hosts
|
|
206
|
-
|
|
207
|
-
These hosts let you register `warden-mcp` directly from the command line:
|
|
66
|
+
### Codex
|
|
208
67
|
|
|
209
68
|
```bash
|
|
210
|
-
# Codex
|
|
211
69
|
codex mcp add warden \
|
|
212
70
|
--env BW_HOST=https://vaultwarden.example.com \
|
|
213
71
|
--env BW_CLIENTID=user.xxxxx \
|
|
214
72
|
--env BW_CLIENTSECRET=xxxxx \
|
|
215
73
|
--env BW_PASSWORD='your-master-password' \
|
|
216
74
|
-- npx -y @icoretech/warden-mcp@latest --stdio
|
|
217
|
-
|
|
218
|
-
# Claude Code
|
|
219
|
-
claude mcp add-json warden '{"command":"npx","args":["-y","@icoretech/warden-mcp@latest","--stdio"],"env":{"BW_HOST":"https://vaultwarden.example.com","BW_CLIENTID":"user.xxxxx","BW_CLIENTSECRET":"xxxxx","BW_PASSWORD":"your-master-password"}}'
|
|
220
75
|
```
|
|
221
76
|
|
|
222
|
-
|
|
77
|
+
Codex TOML config:
|
|
223
78
|
|
|
224
|
-
|
|
79
|
+
```toml
|
|
80
|
+
[mcp_servers.warden]
|
|
81
|
+
command = "npx"
|
|
82
|
+
args = ["-y", "@icoretech/warden-mcp@latest", "--stdio"]
|
|
83
|
+
startup_timeout_sec = 30
|
|
225
84
|
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
85
|
+
[mcp_servers.warden.env]
|
|
86
|
+
BW_HOST = "https://vaultwarden.example.com"
|
|
87
|
+
BW_CLIENTID = "user.xxxxx"
|
|
88
|
+
BW_CLIENTSECRET = "xxxxx"
|
|
89
|
+
BW_PASSWORD = "your-master-password"
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`startup_timeout_sec = 30` gives `npx` enough time for a cold first launch.
|
|
229
93
|
|
|
230
|
-
|
|
94
|
+
### Cursor, Claude Desktop, And JSON Config Hosts
|
|
231
95
|
|
|
232
96
|
```json
|
|
233
97
|
{
|
|
@@ -246,115 +110,85 @@ Shared JSON shape:
|
|
|
246
110
|
}
|
|
247
111
|
```
|
|
248
112
|
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
```toml
|
|
252
|
-
[mcp_servers.warden]
|
|
253
|
-
command = "npx"
|
|
254
|
-
args = ["-y", "@icoretech/warden-mcp@latest", "--stdio"]
|
|
255
|
-
startup_timeout_sec = 30
|
|
113
|
+
Common locations:
|
|
256
114
|
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
115
|
+
| Host | Config file |
|
|
116
|
+
| --- | --- |
|
|
117
|
+
| Cursor | `~/.cursor/mcp.json` or `.cursor/mcp.json` |
|
|
118
|
+
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
|
|
119
|
+
| Codex | `~/.codex/config.toml` |
|
|
120
|
+
|
|
121
|
+
## Why Use It
|
|
122
|
+
|
|
123
|
+
- **Agent login flows** - fetch usernames, passwords, and TOTP codes during real
|
|
124
|
+
browser automation without storing secrets in the agent prompt
|
|
125
|
+
- **Safe by default** - secret fields stay redacted unless a tool supports
|
|
126
|
+
`reveal: true` and the client explicitly asks for it
|
|
127
|
+
- **Vault administration** - create, update, move, restore, and delete common
|
|
128
|
+
Bitwarden item types, folders, organization collections, attachments, and Sends
|
|
129
|
+
- **Shared HTTP mode** - one long-running service can front multiple vault hosts
|
|
130
|
+
or identities through per-request `X-BW-*` headers
|
|
131
|
+
- **Text-only client support** - safe identifiers are mirrored into text output
|
|
132
|
+
for MCP hosts that ignore `structuredContent`
|
|
133
|
+
- **Vaultwarden-first CI** - the integration suite exercises real local
|
|
134
|
+
Vaultwarden and `bw` auth/session flows, not only mocked SDK behavior
|
|
277
135
|
|
|
278
|
-
|
|
279
|
-
validate Bitwarden credentials:
|
|
136
|
+
## How It Works
|
|
280
137
|
|
|
281
|
-
```
|
|
282
|
-
|
|
138
|
+
```mermaid
|
|
139
|
+
flowchart LR
|
|
140
|
+
Agent["AI agent or MCP client"] --> Transport["stdio or Streamable HTTP"]
|
|
141
|
+
Transport --> Server["warden-mcp"]
|
|
142
|
+
Server --> BW["Bitwarden CLI (bw)"]
|
|
143
|
+
BW --> Vault["Vaultwarden or Bitwarden"]
|
|
144
|
+
Server --> State["per-profile bw state"]
|
|
283
145
|
```
|
|
284
146
|
|
|
285
|
-
|
|
286
|
-
`
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
- `X-BW-Password`
|
|
290
|
-
- either `X-BW-ClientId` + `X-BW-ClientSecret`, or `X-BW-User` / `X-BW-Username`
|
|
291
|
-
- optional `X-BW-Unlock-Interval` in seconds; default `300`
|
|
147
|
+
`warden-mcp` shells out to `bw` and keeps profile state under
|
|
148
|
+
`KEYCHAIN_BW_HOME_ROOT`. In HTTP mode, profile selection and credentials come
|
|
149
|
+
from request headers. In stdio mode, credentials are loaded from `BW_*` env vars
|
|
150
|
+
when the process starts.
|
|
292
151
|
|
|
293
|
-
|
|
152
|
+
The HTTP server exposes:
|
|
294
153
|
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
154
|
+
| Endpoint | Purpose |
|
|
155
|
+
| --- | --- |
|
|
156
|
+
| `GET /healthz` | liveness check; does not validate vault credentials |
|
|
157
|
+
| `GET /metricsz` | session and runtime guardrail metrics |
|
|
158
|
+
| `/sse?v=2` | MCP Streamable HTTP endpoint |
|
|
300
159
|
|
|
301
|
-
|
|
302
|
-
- you want to rotate vault credentials per request instead of per process
|
|
303
|
-
- you are integrating from a custom client or agent host that can attach HTTP headers
|
|
304
|
-
- you want one always-on service instead of each editor spawning its own `bw`-backed subprocess
|
|
160
|
+
## Run As A Shared HTTP Service
|
|
305
161
|
|
|
306
|
-
|
|
162
|
+
HTTP mode is useful when one service should serve multiple clients or multiple
|
|
163
|
+
vault profiles.
|
|
307
164
|
|
|
308
|
-
|
|
309
|
-
attach custom `X-BW-*` headers. In that case, run `warden-mcp` as a
|
|
310
|
-
single-tenant shared server with fixed server-side credentials and explicit env
|
|
311
|
-
fallback enabled:
|
|
165
|
+
Start the server:
|
|
312
166
|
|
|
313
167
|
```bash
|
|
314
|
-
BW_HOST=https://vaultwarden.example.com \
|
|
315
|
-
BW_CLIENTID=user.xxxxx \
|
|
316
|
-
BW_CLIENTSECRET=xxxxx \
|
|
317
|
-
BW_PASSWORD='your-master-password' \
|
|
318
|
-
KEYCHAIN_ALLOW_ENV_FALLBACK=true \
|
|
319
168
|
npx -y @icoretech/warden-mcp@latest
|
|
320
169
|
```
|
|
321
170
|
|
|
322
|
-
|
|
323
|
-
over **HTTPS** rather than plain `http://localhost:3005/...`.
|
|
324
|
-
|
|
325
|
-
If you are running `warden-mcp` locally, that usually means putting one of
|
|
326
|
-
these in front of it:
|
|
327
|
-
|
|
328
|
-
- a local HTTPS reverse proxy in front of `warden-mcp`
|
|
329
|
-
- a temporary tunnel such as Cloudflare Tunnel, ngrok, or Tailscale Funnel
|
|
171
|
+
Verify liveness:
|
|
330
172
|
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
```text
|
|
334
|
-
https://warden-mcp.example.com/sse?v=2
|
|
173
|
+
```bash
|
|
174
|
+
curl -fsS http://localhost:3005/healthz
|
|
335
175
|
```
|
|
336
176
|
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
`BW_USER` + `BW_PASSWORD` here as well; the example above shows the API-key
|
|
340
|
-
variant because it is the default convention used elsewhere in this README.
|
|
341
|
-
|
|
342
|
-
Important limits:
|
|
343
|
-
|
|
344
|
-
- this is single-tenant only: every headerless client gets the same vault identity
|
|
345
|
-
- per-request profile switching does not work in this mode
|
|
346
|
-
- if a client can send `X-BW-*` headers, those headers still take priority over the server env
|
|
347
|
-
- anyone who can reach that endpoint inherits that vault access, so keep it behind trusted network access, VPN, tunnel access policies, IP allowlists, or another private boundary
|
|
177
|
+
MCP tool calls must include these headers unless env fallback is explicitly
|
|
178
|
+
enabled:
|
|
348
179
|
|
|
349
|
-
|
|
180
|
+
| Header | Meaning |
|
|
181
|
+
| --- | --- |
|
|
182
|
+
| `X-BW-Host` | HTTPS origin only, for example `https://vaultwarden.example.com` |
|
|
183
|
+
| `X-BW-Password` | master password used to unlock the vault |
|
|
184
|
+
| `X-BW-ClientId` | Bitwarden API key client id |
|
|
185
|
+
| `X-BW-ClientSecret` | Bitwarden API key client secret |
|
|
186
|
+
| `X-BW-User` or `X-BW-Username` | username/email alternative to API key login |
|
|
187
|
+
| `X-BW-Unlock-Interval` | optional unlock interval in seconds; default `300` |
|
|
350
188
|
|
|
351
|
-
|
|
352
|
-
# Claude Code
|
|
353
|
-
claude mcp add-json warden '{"type":"http","url":"http://localhost:3005/sse?v=2","headers":{"X-BW-Host":"https://vaultwarden.example.com","X-BW-ClientId":"user.xxxxx","X-BW-ClientSecret":"xxxxx","X-BW-Password":"your-master-password"}}'
|
|
354
|
-
```
|
|
189
|
+
Example HTTP MCP config for hosts that support custom headers:
|
|
355
190
|
|
|
356
191
|
```json
|
|
357
|
-
// Cursor (~/.cursor/mcp.json)
|
|
358
192
|
{
|
|
359
193
|
"mcpServers": {
|
|
360
194
|
"warden": {
|
|
@@ -370,263 +204,229 @@ claude mcp add-json warden '{"type":"http","url":"http://localhost:3005/sse?v=2"
|
|
|
370
204
|
}
|
|
371
205
|
```
|
|
372
206
|
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
```bash
|
|
378
|
-
bw --version
|
|
379
|
-
```
|
|
380
|
-
|
|
381
|
-
If that fails after install, your environment likely skipped the optional `@bitwarden/cli` dependency. Install it explicitly:
|
|
382
|
-
|
|
383
|
-
```bash
|
|
384
|
-
npm install -g @bitwarden/cli@2026.5.0
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
## How It Works
|
|
388
|
-
|
|
389
|
-
The server executes `bw` commands on your behalf:
|
|
390
|
-
|
|
391
|
-
- In HTTP mode, Bitwarden/Vaultwarden credentials are provided via **HTTP headers** for tool calls. Env-var fallback is disabled by default; set `KEYCHAIN_ALLOW_ENV_FALLBACK=true` only for single-tenant HTTP deployments.
|
|
392
|
-
- In stdio mode, Bitwarden/Vaultwarden credentials are loaded once from `BW_*` env vars at startup.
|
|
393
|
-
- The server maintains per-profile `bw` state under `KEYCHAIN_BW_HOME_ROOT` and pins `BITWARDENCLI_APPDATA_DIR` inside that profile so the Bitwarden CLI keeps a stable local device/app identity across restarts instead of looking like a fresh client every time.
|
|
394
|
-
- Writes call `bw sync` before mutations by default; set `KEYCHAIN_SYNC_ON_WRITE=false` to skip that pre-write sync. Manual sync is also exposed as `keychain_sync`.
|
|
395
|
-
|
|
396
|
-
Timeout handling is also process-tree aware: if a `bw` command hangs, `warden-mcp` kills the full spawned process group rather than only the direct parent process. That prevents timed-out auth attempts from leaving orphaned `bw`/shell child processes behind.
|
|
397
|
-
|
|
398
|
-
### Bitwarden credential inputs
|
|
399
|
-
|
|
400
|
-
- `X-BW-Host` / `BW_HOST` (must be an HTTPS origin, for example `https://vaultwarden.example.com`; no path, query, fragment, or embedded credentials)
|
|
401
|
-
- `X-BW-Password` / `BW_PASSWORD` (master password; required to unlock)
|
|
402
|
-
- Either:
|
|
403
|
-
- `X-BW-ClientId` + `X-BW-ClientSecret` / `BW_CLIENTID` + `BW_CLIENTSECRET` (API key login), or
|
|
404
|
-
- `X-BW-User` / `X-BW-Username` / `BW_USER` / `BW_USERNAME` (email for user/pass login; still uses the master password)
|
|
405
|
-
- Optional unlock interval:
|
|
406
|
-
- `X-BW-Unlock-Interval` / `BW_UNLOCK_INTERVAL` in seconds; default `300`
|
|
407
|
-
|
|
408
|
-
## Security Model
|
|
409
|
-
|
|
410
|
-
There is **no built-in auth** layer in v1. Run it only on a trusted network boundary (localhost, private subnet, VPN, etc.).
|
|
411
|
-
|
|
412
|
-
Credential resolution:
|
|
413
|
-
|
|
414
|
-
- **HTTP mode** requires `X-BW-*` headers before Bitwarden-backed tools can run by default. `/healthz` and `/metricsz` do not validate vault credentials.
|
|
415
|
-
- **Stdio mode** reads `BW_*` env vars at startup (single-tenant).
|
|
416
|
-
- To allow HTTP mode to fall back to server env vars when headers are absent (single-tenant HTTP), set `KEYCHAIN_ALLOW_ENV_FALLBACK=true`. **Security warning:** this means any client that can reach the HTTP endpoint gets full vault access without providing credentials. Only use this behind network-level access control.
|
|
417
|
-
|
|
418
|
-
Runtime and safety controls:
|
|
419
|
-
|
|
420
|
-
- Set `PORT` to change the HTTP port (default `3005`).
|
|
421
|
-
- Set `WARDEN_MCP_HOST` to bind the HTTP server to a specific interface, for example `127.0.0.1` for local-only access.
|
|
422
|
-
- Set `WARDEN_MCP_STDIO=true` as an env-var alternative to `--stdio`.
|
|
423
|
-
- Set `MCP_APP_NAME` to override the advertised MCP server name.
|
|
424
|
-
- Tool names default to `keychain_*`. Override `TOOL_PREFIX` to change the namespace and `TOOL_SEPARATOR` to change the separator (default `_`, set `.` for legacy clients).
|
|
425
|
-
- Set `KEYCHAIN_BW_HOME_ROOT` to change where per-profile `bw` state is stored.
|
|
426
|
-
- Set `KEYCHAIN_SYNC_ON_WRITE=false` to skip the default pre-write `bw sync` call.
|
|
427
|
-
- Set `READONLY=true` or `KEYCHAIN_READONLY=true` to hide mutating tools from the advertised MCP catalog and reject direct write calls. This covers item/folder/org collection writes, Sends, attachments, batch creates/deletes, URI updates, moves, and restores.
|
|
428
|
-
- Set `NOREVEAL=true` or `KEYCHAIN_NOREVEAL=true` to force all `reveal` parameters to `false` server-side. Clients can still request `reveal: true`, but the server will silently downgrade to redacted output. This prevents prompt injection from tricking an LLM agent into exfiltrating secrets.
|
|
429
|
-
- Set `KEYCHAIN_TEXT_COMPAT_MODE=structured_json` to mirror supported structured tool results into `TextContent` as serialized JSON. This is useful for text-only MCP clients that ignore `structuredContent`, but it also duplicates revealed secrets into the plain-text transcript.
|
|
430
|
-
|
|
431
|
-
Session guardrails:
|
|
432
|
-
|
|
433
|
-
- `KEYCHAIN_SESSION_MAX_COUNT` (default `32`)
|
|
434
|
-
- `KEYCHAIN_SESSION_TTL_MS` (default `900000`)
|
|
435
|
-
- `KEYCHAIN_SESSION_SWEEP_INTERVAL_MS` (default `60000`)
|
|
436
|
-
- `KEYCHAIN_MAX_HEAP_USED_MB` (default `1536`, set `0` to disable memory fuse)
|
|
437
|
-
- `KEYCHAIN_METRICS_LOG_INTERVAL_MS` (default `0`, disabled)
|
|
438
|
-
|
|
439
|
-
Redaction defaults (item reads):
|
|
440
|
-
|
|
441
|
-
- Login: `password`, `totp`
|
|
442
|
-
- Card: `number`, `code`
|
|
443
|
-
- Identity: `ssn`, `passportNumber`, `licenseNumber`
|
|
444
|
-
- Custom fields: hidden fields (Bitwarden `type: 1`)
|
|
445
|
-
- SSH key convention: custom field `private_key` is always redacted
|
|
446
|
-
- Attachments: `attachments[].url` (signed download URL token)
|
|
447
|
-
- Password history: `passwordHistory[].password`
|
|
448
|
-
|
|
449
|
-
Reveal rules:
|
|
450
|
-
|
|
451
|
-
- Tools accept `reveal: true` where applicable (default is `false`).
|
|
452
|
-
- Secret helper tools (`get_password`, `get_totp`, `get_notes`, `generate`, `generate_username`, `get_password_history`) return `structuredContent.result = { kind, value, revealed }`.
|
|
453
|
-
- When `reveal` is omitted/false, `value` is `null` (or historic passwords are `null`) and `revealed: false`.
|
|
454
|
-
|
|
455
|
-
## Production Deployment Checklist
|
|
456
|
-
|
|
457
|
-
If you run `warden-mcp` beyond local development, review these items:
|
|
458
|
-
|
|
459
|
-
1. **TLS everywhere.** Always terminate TLS in front of the HTTP endpoint. `X-BW-*` headers carry master passwords in cleartext — without TLS they are visible to anyone on the network.
|
|
460
|
-
|
|
461
|
-
2. **Network isolation.** Bind or publish the server only on a trusted interface, for example `WARDEN_MCP_HOST=127.0.0.1`, Docker `-p 127.0.0.1:3005:3005`, a firewall, VPN, or an authenticated reverse proxy. The service has no built-in authentication; anyone who can reach `/sse` can issue vault operations.
|
|
462
|
-
|
|
463
|
-
3. **Do not enable `KEYCHAIN_ALLOW_ENV_FALLBACK` on shared networks.** This flag makes the server's own vault credentials available to any HTTP client that omits headers. Only use it in single-tenant setups where the network is fully trusted.
|
|
464
|
-
|
|
465
|
-
4. **Enable `READONLY=true` or `KEYCHAIN_READONLY=true` when writes are not needed.** This hides mutating tools from the advertised MCP catalog and rejects direct write calls at the MCP layer, limiting blast radius if an agent or client is compromised.
|
|
466
|
-
|
|
467
|
-
5. **Persist and restrict filesystem access to the configured `KEYCHAIN_BW_HOME_ROOT`.** In Docker the default is `/data/bw-profiles`; on host runs it defaults to `${HOME}/bw-profiles`. Ensure the profile directory is not world-readable and is mounted with appropriate permissions (the Docker image runs as non-root uid/gid `1000`).
|
|
468
|
-
|
|
469
|
-
6. **Disable debug logging in production.** `KEYCHAIN_DEBUG_BW` and `KEYCHAIN_DEBUG_HTTP` emit request details and CLI invocations to stdout. Debug logs may include session metadata and request structure. Keep them off unless actively troubleshooting.
|
|
470
|
-
|
|
471
|
-
7. **Set `NOREVEAL=true` when secrets should never leave the server.** This forces all `reveal` parameters to `false` server-side, regardless of what the client requests. Use this when the MCP host is an LLM agent that could be influenced by prompt injection — it prevents tricked agents from exfiltrating passwords or TOTP codes.
|
|
472
|
-
|
|
473
|
-
8. **Monitor `/metricsz`.** The endpoint is intentionally unauthenticated (for scraper compatibility) but exposes session counts, heap usage, and rejection counters. If this data is sensitive in your environment, restrict access at the network level.
|
|
474
|
-
|
|
475
|
-
9. **Only enable `KEYCHAIN_TEXT_COMPAT_MODE=structured_json` for text-only clients you trust.** It improves compatibility with clients that ignore `structuredContent`, but any revealed secret will also appear in plain-text `TextContent`, making transcript leakage easier.
|
|
476
|
-
|
|
477
|
-
## Quick Start
|
|
478
|
-
|
|
479
|
-
### Minimal local run
|
|
480
|
-
|
|
481
|
-
Run the published package in HTTP mode and verify the server is up:
|
|
207
|
+
Some browser-hosted MCP clients can connect to an HTTP/SSE endpoint but cannot
|
|
208
|
+
send custom `X-BW-*` headers. For those clients, run a single-tenant HTTP server
|
|
209
|
+
with env fallback:
|
|
482
210
|
|
|
483
211
|
```bash
|
|
212
|
+
BW_HOST=https://vaultwarden.example.com \
|
|
213
|
+
BW_CLIENTID=user.xxxxx \
|
|
214
|
+
BW_CLIENTSECRET=xxxxx \
|
|
215
|
+
BW_PASSWORD='your-master-password' \
|
|
216
|
+
KEYCHAIN_ALLOW_ENV_FALLBACK=true \
|
|
484
217
|
npx -y @icoretech/warden-mcp@latest
|
|
485
|
-
curl -fsS http://localhost:3005/healthz
|
|
486
218
|
```
|
|
487
219
|
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
### Docker Compose
|
|
220
|
+
Only use `KEYCHAIN_ALLOW_ENV_FALLBACK=true` behind a trusted network boundary.
|
|
221
|
+
Every client that can reach the endpoint inherits the configured vault identity.
|
|
491
222
|
|
|
492
|
-
|
|
223
|
+
For hosted clients that require HTTPS, put a reverse proxy, private tunnel, VPN,
|
|
224
|
+
or equivalent protected endpoint in front of `warden-mcp`, then connect to:
|
|
493
225
|
|
|
494
|
-
```
|
|
495
|
-
|
|
496
|
-
make up
|
|
226
|
+
```text
|
|
227
|
+
https://warden-mcp.example.com/sse?v=2
|
|
497
228
|
```
|
|
498
229
|
|
|
499
|
-
|
|
500
|
-
the server is up:
|
|
230
|
+
## Docker
|
|
501
231
|
|
|
502
232
|
```bash
|
|
503
|
-
|
|
233
|
+
docker run --rm \
|
|
234
|
+
-p 127.0.0.1:3005:3005 \
|
|
235
|
+
-v warden-mcp-data:/data \
|
|
236
|
+
ghcr.io/icoretech/warden-mcp:latest
|
|
504
237
|
```
|
|
505
238
|
|
|
506
|
-
|
|
239
|
+
The production image runs as the non-root `node` user with uid/gid `1000`, sets
|
|
240
|
+
`HOME=/data`, and stores Bitwarden profile state under `/data/bw-profiles` by
|
|
241
|
+
default. If you use a bind mount, make it writable by uid/gid `1000`.
|
|
507
242
|
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
243
|
+
## Runtime Requirements
|
|
244
|
+
|
|
245
|
+
`warden-mcp` requires Node.js 24+ when running from npm or source. The Docker
|
|
246
|
+
image includes the supported Node runtime.
|
|
511
247
|
|
|
512
|
-
|
|
513
|
-
raw CLI plus MCP/SDK layers:
|
|
248
|
+
The server resolves `bw` in this order:
|
|
514
249
|
|
|
515
|
-
|
|
516
|
-
|
|
250
|
+
1. `BW_BIN`, when set
|
|
251
|
+
2. bundled `@bitwarden/cli` optional dependency, when installed
|
|
252
|
+
3. system `bw` from `PATH`
|
|
517
253
|
|
|
518
|
-
The
|
|
519
|
-
|
|
520
|
-
change.
|
|
254
|
+
The bundled `@bitwarden/cli` version is currently `2026.6.0`. This project keeps
|
|
255
|
+
that version vetted instead of blindly tracking every upstream release, because
|
|
256
|
+
auth and unlock behavior can change in ways that break automation.
|
|
521
257
|
|
|
522
|
-
|
|
258
|
+
If your package manager skips optional dependencies and `bw` is missing, install
|
|
259
|
+
the CLI explicitly or point `BW_BIN` to a known binary:
|
|
523
260
|
|
|
524
261
|
```bash
|
|
525
|
-
|
|
262
|
+
npm install -g @bitwarden/cli@2026.6.0
|
|
263
|
+
BW_BIN=/absolute/path/to/bw npx -y @icoretech/warden-mcp@latest --stdio
|
|
526
264
|
```
|
|
527
265
|
|
|
528
|
-
|
|
529
|
-
you need to inspect that stack manually.
|
|
266
|
+
## Security Model
|
|
530
267
|
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
268
|
+
There is no built-in authentication layer in v1. Protect the transport before
|
|
269
|
+
you expose it.
|
|
270
|
+
|
|
271
|
+
- **Bind locally by default** - use `WARDEN_MCP_HOST=127.0.0.1`, Docker
|
|
272
|
+
`-p 127.0.0.1:3005:3005`, a firewall, VPN, or an authenticated reverse proxy
|
|
273
|
+
- **Use TLS for HTTP mode** - `X-BW-*` headers carry vault credentials
|
|
274
|
+
- **Avoid env fallback on shared networks** - `KEYCHAIN_ALLOW_ENV_FALLBACK=true`
|
|
275
|
+
makes server-side vault credentials available to headerless clients
|
|
276
|
+
- **Use read-only mode when writes are not needed** - `READONLY=true` or
|
|
277
|
+
`KEYCHAIN_READONLY=true` hides mutating tools and rejects direct write calls
|
|
278
|
+
- **Use no-reveal mode for untrusted agent contexts** - `NOREVEAL=true` or
|
|
279
|
+
`KEYCHAIN_NOREVEAL=true` forces all secret-returning tools to stay redacted
|
|
280
|
+
- **Keep debug logs off in production** - do not enable `KEYCHAIN_DEBUG_BW` or
|
|
281
|
+
`KEYCHAIN_DEBUG_HTTP` unless actively troubleshooting
|
|
282
|
+
- **Restrict profile storage** - protect `KEYCHAIN_BW_HOME_ROOT`, which stores
|
|
283
|
+
local `bw` profile state
|
|
284
|
+
- **Protect `/metricsz` if needed** - it is unauthenticated for scraper
|
|
285
|
+
compatibility and exposes runtime/session counters
|
|
286
|
+
|
|
287
|
+
Redacted fields include login passwords, TOTP seeds/codes, card numbers and
|
|
288
|
+
codes, identity SSNs/passport/license numbers, hidden custom fields, SSH private
|
|
289
|
+
keys stored through the secure-note convention, signed attachment URLs, and
|
|
290
|
+
password history entries.
|
|
291
|
+
|
|
292
|
+
## Configuration
|
|
293
|
+
|
|
294
|
+
| Variable | Default | Purpose |
|
|
295
|
+
| --- | --- | --- |
|
|
296
|
+
| `PORT` | `3005` | HTTP listen port |
|
|
297
|
+
| `WARDEN_MCP_HOST` | all interfaces | HTTP bind host |
|
|
298
|
+
| `WARDEN_MCP_STDIO` | `false` | force stdio mode without `--stdio` |
|
|
299
|
+
| `MCP_APP_NAME` | `keychain-mcp` | advertised MCP server name |
|
|
300
|
+
| `TOOL_PREFIX` | `keychain` | public tool namespace |
|
|
301
|
+
| `TOOL_SEPARATOR` | `_` | public tool separator; set `.` for legacy clients |
|
|
302
|
+
| `KEYCHAIN_BW_HOME_ROOT` | `${HOME}/bw-profiles` | root for per-profile `bw` state |
|
|
303
|
+
| `KEYCHAIN_ALLOW_ENV_FALLBACK` | `false` | allow HTTP calls to inherit server `BW_*` env |
|
|
304
|
+
| `KEYCHAIN_SYNC_ON_WRITE` | `true` | run `bw sync` before write operations |
|
|
305
|
+
| `READONLY` / `KEYCHAIN_READONLY` | `false` | hide and reject mutating tools |
|
|
306
|
+
| `NOREVEAL` / `KEYCHAIN_NOREVEAL` | `false` | force `reveal: false` server-side |
|
|
307
|
+
| `KEYCHAIN_TEXT_COMPAT_MODE` | unset | set `structured_json` for text-only clients |
|
|
308
|
+
| `KEYCHAIN_SESSION_MAX_COUNT` | `32` | max tracked HTTP sessions |
|
|
309
|
+
| `KEYCHAIN_SESSION_TTL_MS` | `900000` | inactive session TTL |
|
|
310
|
+
| `KEYCHAIN_SESSION_SWEEP_INTERVAL_MS` | `60000` | session cleanup interval |
|
|
311
|
+
| `KEYCHAIN_MAX_HEAP_USED_MB` | `1536` | memory fuse; set `0` to disable |
|
|
312
|
+
| `KEYCHAIN_METRICS_LOG_INTERVAL_MS` | `0` | periodic metrics logging; `0` disables |
|
|
313
|
+
|
|
314
|
+
`KEYCHAIN_TEXT_COMPAT_MODE=structured_json` mirrors supported
|
|
315
|
+
`structuredContent` into plain text. That helps MCP clients that only pass
|
|
316
|
+
`content[]` to the model, but any revealed secret will also appear in the text
|
|
317
|
+
transcript.
|
|
318
|
+
|
|
319
|
+
## Tool Reference
|
|
320
|
+
|
|
321
|
+
Tool names default to `keychain_*`. Change the prefix with `TOOL_PREFIX` and the
|
|
322
|
+
separator with `TOOL_SEPARATOR`.
|
|
323
|
+
|
|
324
|
+
Start with these:
|
|
325
|
+
|
|
326
|
+
- `keychain_status` - inspect raw `bw` status
|
|
327
|
+
- `keychain_sync` - pull latest vault data with `bw sync`
|
|
328
|
+
- `keychain_search_items` - find items by name, URI, username, folder,
|
|
329
|
+
collection, or type
|
|
330
|
+
- `keychain_get_item` - read a full item by id, redacted by default
|
|
331
|
+
- `keychain_get_username`, `keychain_get_password`, `keychain_get_totp` - fetch
|
|
332
|
+
common login values; password and TOTP require `reveal: true`
|
|
333
|
+
- `keychain_create_login`, `keychain_update_item`,
|
|
334
|
+
`keychain_move_item_to_organization` - common write paths
|
|
335
|
+
|
|
336
|
+
Full tool groups:
|
|
337
|
+
|
|
338
|
+
| Group | Tools |
|
|
339
|
+
| --- | --- |
|
|
340
|
+
| Vault/session | `keychain_status`, `keychain_sync`, `keychain_sdk_version`, `keychain_encode`, `keychain_generate`, `keychain_generate_username` |
|
|
341
|
+
| Items | `keychain_search_items`, `keychain_get_item`, `keychain_update_item`, `keychain_create_login`, `keychain_create_logins`, `keychain_set_login_uris`, `keychain_create_note`, `keychain_create_card`, `keychain_create_identity`, `keychain_create_ssh_key`, `keychain_delete_item`, `keychain_delete_items`, `keychain_restore_item` |
|
|
342
|
+
| Folders | `keychain_list_folders`, `keychain_create_folder`, `keychain_edit_folder`, `keychain_delete_folder` |
|
|
343
|
+
| Organizations and collections | `keychain_list_organizations`, `keychain_list_collections`, `keychain_list_org_collections`, `keychain_create_org_collection`, `keychain_edit_org_collection`, `keychain_delete_org_collection`, `keychain_move_item_to_organization` |
|
|
344
|
+
| Attachments | `keychain_create_attachment`, `keychain_delete_attachment`, `keychain_get_attachment` |
|
|
345
|
+
| Sends | `keychain_send_list`, `keychain_send_template`, `keychain_send_get`, `keychain_send_create`, `keychain_send_create_encoded`, `keychain_send_edit`, `keychain_send_remove_password`, `keychain_send_delete`, `keychain_receive` |
|
|
346
|
+
| Direct `bw get` helpers | `keychain_get_username`, `keychain_get_password`, `keychain_get_totp`, `keychain_get_notes`, `keychain_get_uri`, `keychain_get_exposed`, `keychain_get_folder`, `keychain_get_collection`, `keychain_get_organization`, `keychain_get_org_collection`, `keychain_get_password_history` |
|
|
347
|
+
|
|
348
|
+
Notes:
|
|
349
|
+
|
|
350
|
+
- `keychain_create_logins` creates several independent login items in one call
|
|
351
|
+
and reports per-item failures without aborting the whole batch
|
|
352
|
+
- `keychain_set_login_uris` replaces or merges a login item's URI list without
|
|
353
|
+
editing the entire item payload
|
|
354
|
+
- `keychain_delete_items` supports bulk soft-delete or hard-delete by id
|
|
355
|
+
- `keychain_get_item` exposes safe attachment metadata, including `id`,
|
|
356
|
+
`fileName`, and size, while redacting signed download URLs
|
|
357
|
+
- `keychain_get_attachment` accepts an attachment id or an unambiguous filename
|
|
358
|
+
and returns `{ filename, bytes, contentBase64 }`
|
|
359
|
+
- `keychain_send_get` returns owned Send metadata and text content; use
|
|
360
|
+
`keychain_receive` with a Send `accessUrl` to receive shared Sends or download
|
|
361
|
+
file Send bytes
|
|
362
|
+
- Ambiguous login lookups return `AMBIGUOUS_LOOKUP` with visible candidate ids;
|
|
363
|
+
retry with the exact item id
|
|
534
364
|
|
|
535
|
-
|
|
536
|
-
npm run test:session-regression
|
|
537
|
-
```
|
|
365
|
+
## Local Development
|
|
538
366
|
|
|
539
|
-
|
|
367
|
+
Use Docker Compose when you need the full Vaultwarden-backed stack.
|
|
540
368
|
|
|
541
369
|
```bash
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
npm run dev
|
|
370
|
+
cp .env.example .env
|
|
371
|
+
make up
|
|
545
372
|
```
|
|
546
373
|
|
|
547
|
-
|
|
548
|
-
|
|
374
|
+
`make up` starts local Vaultwarden, an HTTPS proxy for `bw`, bootstraps a test
|
|
375
|
+
account, and runs the MCP server in the foreground.
|
|
549
376
|
|
|
550
|
-
Useful
|
|
377
|
+
Useful commands:
|
|
551
378
|
|
|
552
|
-
|
|
|
379
|
+
| Command | Purpose |
|
|
553
380
|
| --- | --- |
|
|
554
|
-
| `npm run
|
|
555
|
-
| `npm run
|
|
556
|
-
| `npm run start` |
|
|
557
|
-
| `npm run
|
|
558
|
-
| `npm run test
|
|
559
|
-
| `npm run test:
|
|
560
|
-
| `npm run
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
Vault/session:
|
|
381
|
+
| `npm run dev` | watch-mode server from source |
|
|
382
|
+
| `npm run build` | compile TypeScript to `dist/` |
|
|
383
|
+
| `npm run start` | run the compiled server |
|
|
384
|
+
| `npm run lint` | Biome autofix plus `tsc --noEmit` |
|
|
385
|
+
| `npm run test` | build, then run all compiled tests |
|
|
386
|
+
| `npm run test:integration` | build, then run compose-backed integration tests |
|
|
387
|
+
| `npm run test:coverage` | build, then run Node test coverage |
|
|
388
|
+
| `make test` | run the compose-backed Vaultwarden integration path |
|
|
389
|
+
| `make test-org` | run the organization-focused compose stack |
|
|
390
|
+
| `make down` | stop the local compose stack |
|
|
391
|
+
|
|
392
|
+
For a quick live MCP smoke against local Vaultwarden, see
|
|
393
|
+
[agent-instructions/testing.md](agent-instructions/testing.md).
|
|
394
|
+
|
|
395
|
+
## Compatibility
|
|
396
|
+
|
|
397
|
+
Vaultwarden is the continuously proven target in CI. Official Bitwarden
|
|
398
|
+
compatibility is intended, but it is not continuously proven without a real
|
|
399
|
+
Bitwarden tenant.
|
|
400
|
+
|
|
401
|
+
`@bitwarden/cli` upgrades are treated as compatibility decisions. The suite
|
|
402
|
+
checks direct `bw` auth behavior, SDK behavior, and MCP integration behavior
|
|
403
|
+
against a local Vaultwarden instance before a CLI bump should ship.
|
|
578
404
|
|
|
579
|
-
|
|
580
|
-
- `keychain_sync` (pull latest vault data from server via `bw sync`)
|
|
581
|
-
- `keychain_sdk_version` (returns the Bitwarden CLI version reported by `bw --version`)
|
|
582
|
-
- `keychain_encode` (base64-encode a string via `bw encode`)
|
|
583
|
-
- `keychain_generate`, `keychain_generate_username` (return generated values only when `reveal: true`)
|
|
584
|
-
|
|
585
|
-
Items:
|
|
586
|
-
|
|
587
|
-
- `keychain_search_items`, `keychain_get_item`, `keychain_update_item`
|
|
588
|
-
- `keychain_create_login`, `keychain_create_logins`, `keychain_set_login_uris`
|
|
589
|
-
- `keychain_create_note`, `keychain_create_card`, `keychain_create_identity`, `keychain_create_ssh_key`
|
|
590
|
-
- `keychain_delete_item`, `keychain_delete_items`, `keychain_restore_item`
|
|
591
|
-
|
|
592
|
-
Folders:
|
|
593
|
-
|
|
594
|
-
- `keychain_list_folders`, `keychain_create_folder`, `keychain_edit_folder`, `keychain_delete_folder`
|
|
595
|
-
|
|
596
|
-
Orgs/collections:
|
|
597
|
-
|
|
598
|
-
- `keychain_list_organizations`, `keychain_list_collections`
|
|
599
|
-
- `keychain_list_org_collections`, `keychain_create_org_collection`, `keychain_edit_org_collection`, `keychain_delete_org_collection`
|
|
600
|
-
- `keychain_move_item_to_organization`
|
|
601
|
-
|
|
602
|
-
Attachments:
|
|
603
|
-
|
|
604
|
-
- `keychain_create_attachment`, `keychain_delete_attachment`, `keychain_get_attachment`
|
|
605
|
-
- `keychain_get_item` exposes safe attachment metadata (`id`, `fileName`, size) while redacting signed download URLs, so clients can discover the exact attachment id before downloading
|
|
606
|
-
- `keychain_get_attachment` accepts an attachment id or an unambiguous filename and returns `{ filename, bytes, contentBase64 }`; decode `contentBase64` locally when you need the original file bytes
|
|
607
|
-
|
|
608
|
-
Sends:
|
|
405
|
+
## Known Limitations
|
|
609
406
|
|
|
610
|
-
- `
|
|
611
|
-
|
|
612
|
-
-
|
|
613
|
-
|
|
614
|
-
- `
|
|
407
|
+
- `bw list items --search`, and therefore `keychain_search_items`, does not
|
|
408
|
+
reliably search inside custom field values
|
|
409
|
+
- SSH keys are stored as secure notes with standard fields until `bw` supports
|
|
410
|
+
native SSH key item creation
|
|
411
|
+
- high-risk `bw` features such as export/import are intentionally not exposed
|
|
412
|
+
- Vaultwarden report pages are not mirrored as MCP tools; the current
|
|
413
|
+
report-like helper is `keychain_get_exposed`
|
|
615
414
|
|
|
616
|
-
|
|
415
|
+
## Project Links
|
|
617
416
|
|
|
618
|
-
-
|
|
619
|
-
-
|
|
620
|
-
-
|
|
621
|
-
-
|
|
622
|
-
-
|
|
417
|
+
- npm package: [`@icoretech/warden-mcp`](https://www.npmjs.com/package/@icoretech/warden-mcp)
|
|
418
|
+
- Docker image: [`ghcr.io/icoretech/warden-mcp`](https://ghcr.io/icoretech/warden-mcp)
|
|
419
|
+
- Changelog: [CHANGELOG.md](CHANGELOG.md)
|
|
420
|
+
- Security policy: [SECURITY.md](SECURITY.md)
|
|
421
|
+
- Threat model: [THREAT_MODEL.md](THREAT_MODEL.md)
|
|
422
|
+
- Repository guidance: [AGENTS.md](AGENTS.md)
|
|
623
423
|
|
|
624
|
-
##
|
|
424
|
+
## Contributing
|
|
625
425
|
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
426
|
+
Issues and PRs are welcome. Run `npm run lint` and the relevant test command
|
|
427
|
+
before opening a PR; use `make test` when behavior depends on real Vaultwarden
|
|
428
|
+
or `bw` interaction.
|
|
629
429
|
|
|
630
|
-
##
|
|
430
|
+
## License
|
|
631
431
|
|
|
632
|
-
|
|
432
|
+
[MIT](LICENSE)
|
package/dist/bw/bwSession.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
// src/bw/bwSession.ts
|
|
2
|
-
import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
|
|
2
|
+
import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
|
|
3
3
|
import { join } from 'node:path';
|
|
4
4
|
import { isBwAuthSessionInvalidError, runBw } from './bwCli.js';
|
|
5
5
|
import { Mutex } from './mutex.js';
|
|
@@ -7,9 +7,38 @@ const POST_LOGIN_UNLOCK_RETRY_ATTEMPTS = 20;
|
|
|
7
7
|
const POST_LOGIN_UNLOCK_RETRY_DELAY_MS = 2_000;
|
|
8
8
|
const PROCESS_LOCK_WAIT_MS = 100;
|
|
9
9
|
const PROCESS_LOCK_TIMEOUT_MS = 90_000;
|
|
10
|
+
const PROCESS_LOCK_OWNER_FILE = 'owner.json';
|
|
10
11
|
function sleep(ms) {
|
|
11
12
|
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
12
13
|
}
|
|
14
|
+
function isProcessLockOwner(value) {
|
|
15
|
+
return (typeof value === 'object' &&
|
|
16
|
+
value !== null &&
|
|
17
|
+
'pid' in value &&
|
|
18
|
+
'createdAt' in value &&
|
|
19
|
+
typeof value.pid === 'number' &&
|
|
20
|
+
Number.isInteger(value.pid) &&
|
|
21
|
+
typeof value.createdAt === 'string');
|
|
22
|
+
}
|
|
23
|
+
function isProcessAlive(pid) {
|
|
24
|
+
if (pid <= 0)
|
|
25
|
+
return false;
|
|
26
|
+
try {
|
|
27
|
+
process.kill(pid, 0);
|
|
28
|
+
return true;
|
|
29
|
+
}
|
|
30
|
+
catch (error) {
|
|
31
|
+
if (!(error instanceof Error))
|
|
32
|
+
throw error;
|
|
33
|
+
return errorCode(error) !== 'ESRCH';
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
function errorCode(error) {
|
|
37
|
+
if (typeof error !== 'object' || error === null || !('code' in error)) {
|
|
38
|
+
return undefined;
|
|
39
|
+
}
|
|
40
|
+
return error.code;
|
|
41
|
+
}
|
|
13
42
|
function requiredEnv(name) {
|
|
14
43
|
const v = process.env[name];
|
|
15
44
|
if (!v) {
|
|
@@ -99,7 +128,9 @@ export class BwSessionManager {
|
|
|
99
128
|
try {
|
|
100
129
|
await this.ensureUnlockedInternal();
|
|
101
130
|
}
|
|
102
|
-
catch {
|
|
131
|
+
catch (error) {
|
|
132
|
+
if (!(error instanceof Error))
|
|
133
|
+
throw error;
|
|
103
134
|
// Keepalive is best-effort; tools will surface failures.
|
|
104
135
|
}
|
|
105
136
|
});
|
|
@@ -236,7 +267,9 @@ export class BwSessionManager {
|
|
|
236
267
|
return base;
|
|
237
268
|
}
|
|
238
269
|
}
|
|
239
|
-
catch {
|
|
270
|
+
catch (error) {
|
|
271
|
+
if (!(error instanceof Error))
|
|
272
|
+
throw error;
|
|
240
273
|
// Fall back to the CLI if local state is absent or unreadable.
|
|
241
274
|
}
|
|
242
275
|
try {
|
|
@@ -419,12 +452,20 @@ export class BwSessionManager {
|
|
|
419
452
|
while (true) {
|
|
420
453
|
try {
|
|
421
454
|
await mkdir(this.processLockDir);
|
|
455
|
+
try {
|
|
456
|
+
await this.writeProcessLockOwner();
|
|
457
|
+
}
|
|
458
|
+
catch (error) {
|
|
459
|
+
await rm(this.processLockDir, { recursive: true, force: true });
|
|
460
|
+
throw error;
|
|
461
|
+
}
|
|
422
462
|
break;
|
|
423
463
|
}
|
|
424
464
|
catch (error) {
|
|
425
|
-
|
|
426
|
-
if (err?.code !== 'EEXIST')
|
|
465
|
+
if (errorCode(error) !== 'EEXIST')
|
|
427
466
|
throw error;
|
|
467
|
+
if (await this.reclaimProcessAuthLockIfStale())
|
|
468
|
+
continue;
|
|
428
469
|
if (Date.now() - startedAt >= PROCESS_LOCK_TIMEOUT_MS) {
|
|
429
470
|
throw new Error(`Timed out waiting for process auth lock after ${PROCESS_LOCK_TIMEOUT_MS}ms`);
|
|
430
471
|
}
|
|
@@ -438,6 +479,36 @@ export class BwSessionManager {
|
|
|
438
479
|
await rm(this.processLockDir, { recursive: true, force: true }).catch(() => { });
|
|
439
480
|
}
|
|
440
481
|
}
|
|
482
|
+
async writeProcessLockOwner() {
|
|
483
|
+
const owner = {
|
|
484
|
+
pid: process.pid,
|
|
485
|
+
createdAt: new Date().toISOString(),
|
|
486
|
+
};
|
|
487
|
+
await writeFile(join(this.processLockDir, PROCESS_LOCK_OWNER_FILE), JSON.stringify(owner), 'utf8');
|
|
488
|
+
}
|
|
489
|
+
async reclaimProcessAuthLockIfStale() {
|
|
490
|
+
const ownerPath = join(this.processLockDir, PROCESS_LOCK_OWNER_FILE);
|
|
491
|
+
try {
|
|
492
|
+
const parsed = JSON.parse(await readFile(ownerPath, 'utf8'));
|
|
493
|
+
if (isProcessLockOwner(parsed) && !isProcessAlive(parsed.pid)) {
|
|
494
|
+
await rm(this.processLockDir, { recursive: true, force: true });
|
|
495
|
+
return true;
|
|
496
|
+
}
|
|
497
|
+
}
|
|
498
|
+
catch (error) {
|
|
499
|
+
if (!(error instanceof SyntaxError)) {
|
|
500
|
+
if (errorCode(error) !== 'ENOENT')
|
|
501
|
+
throw error;
|
|
502
|
+
}
|
|
503
|
+
}
|
|
504
|
+
const lockStats = await stat(this.processLockDir).catch(() => null);
|
|
505
|
+
if (lockStats &&
|
|
506
|
+
Date.now() - lockStats.mtimeMs >= PROCESS_LOCK_TIMEOUT_MS) {
|
|
507
|
+
await rm(this.processLockDir, { recursive: true, force: true });
|
|
508
|
+
return true;
|
|
509
|
+
}
|
|
510
|
+
return false;
|
|
511
|
+
}
|
|
441
512
|
async ensureServerConfigured() {
|
|
442
513
|
if (this.configuredHost === this.env.host)
|
|
443
514
|
return;
|
|
@@ -456,7 +527,9 @@ export class BwSessionManager {
|
|
|
456
527
|
this.configuredHost = this.env.host;
|
|
457
528
|
return;
|
|
458
529
|
}
|
|
459
|
-
catch {
|
|
530
|
+
catch (error) {
|
|
531
|
+
if (!(error instanceof Error))
|
|
532
|
+
throw error;
|
|
460
533
|
// If the CLI data is corrupt/out-of-sync, wiping config is the fastest recovery.
|
|
461
534
|
}
|
|
462
535
|
await this.resetCliProfile();
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"private": false,
|
|
3
3
|
"name": "@icoretech/warden-mcp",
|
|
4
|
-
"version": "0.2.
|
|
4
|
+
"version": "0.2.30",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",
|
|
@@ -44,24 +44,24 @@
|
|
|
44
44
|
"lint": "biome check --write --assist-enabled=true . && tsc --noEmit"
|
|
45
45
|
},
|
|
46
46
|
"dependencies": {
|
|
47
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
47
|
+
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
48
48
|
"express": "^5.2.1",
|
|
49
49
|
"zod": "^4.4.3"
|
|
50
50
|
},
|
|
51
51
|
"optionalDependencies": {
|
|
52
|
-
"@bitwarden/cli": "2026.
|
|
52
|
+
"@bitwarden/cli": "2026.6.0"
|
|
53
53
|
},
|
|
54
54
|
"overrides": {
|
|
55
55
|
"form-data": "4.0.6",
|
|
56
56
|
"tmp": "0.2.7"
|
|
57
57
|
},
|
|
58
58
|
"devDependencies": {
|
|
59
|
-
"@biomejs/biome": "^2.5.
|
|
59
|
+
"@biomejs/biome": "^2.5.6",
|
|
60
60
|
"@types/express": "^5.0.6",
|
|
61
|
-
"@types/node": "^
|
|
62
|
-
"playwright": "1.
|
|
63
|
-
"tsx": "^4.
|
|
64
|
-
"typescript": "^
|
|
61
|
+
"@types/node": "^26.1.2",
|
|
62
|
+
"playwright": "1.62.0",
|
|
63
|
+
"tsx": "^4.23.1",
|
|
64
|
+
"typescript": "^7.0.2"
|
|
65
65
|
},
|
|
66
66
|
"publishConfig": {
|
|
67
67
|
"registry": "https://registry.npmjs.org",
|