@icoretech/warden-mcp 0.2.53 → 0.2.55
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 +59 -64
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -24,7 +24,6 @@ Use stdio mode when a local MCP host launches the server directly. It is the
|
|
|
24
24
|
simplest and most portable setup for desktop agents.
|
|
25
25
|
|
|
26
26
|
Prerequisites:
|
|
27
|
-
|
|
28
27
|
- Node.js 22.x
|
|
29
28
|
- npm 10.x
|
|
30
29
|
- a Vaultwarden or Bitwarden account
|
|
@@ -112,11 +111,11 @@ BW_PASSWORD = "your-master-password"
|
|
|
112
111
|
|
|
113
112
|
Common locations:
|
|
114
113
|
|
|
115
|
-
| Host
|
|
116
|
-
|
|
|
117
|
-
| Cursor
|
|
114
|
+
| Host | Config file |
|
|
115
|
+
| -------------- | ----------------------------------------------------------------- |
|
|
116
|
+
| Cursor | `~/.cursor/mcp.json` or `.cursor/mcp.json` |
|
|
118
117
|
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
|
|
119
|
-
| Codex
|
|
118
|
+
| Codex | `~/.codex/config.toml` |
|
|
120
119
|
|
|
121
120
|
## Why Use It
|
|
122
121
|
|
|
@@ -151,11 +150,11 @@ when the process starts.
|
|
|
151
150
|
|
|
152
151
|
The HTTP server exposes:
|
|
153
152
|
|
|
154
|
-
| Endpoint
|
|
155
|
-
|
|
|
156
|
-
| `GET /healthz`
|
|
157
|
-
| `GET /metricsz` | session and runtime guardrail metrics
|
|
158
|
-
| `/sse?v=2`
|
|
153
|
+
| Endpoint | Purpose |
|
|
154
|
+
| --------------- | --------------------------------------------------- |
|
|
155
|
+
| `GET /healthz` | liveness check; does not validate vault credentials |
|
|
156
|
+
| `GET /metricsz` | session and runtime guardrail metrics |
|
|
157
|
+
| `/sse?v=2` | MCP Streamable HTTP endpoint |
|
|
159
158
|
|
|
160
159
|
## Run As A Shared HTTP Service
|
|
161
160
|
|
|
@@ -177,14 +176,14 @@ curl -fsS http://localhost:3005/healthz
|
|
|
177
176
|
MCP tool calls must include these headers unless env fallback is explicitly
|
|
178
177
|
enabled:
|
|
179
178
|
|
|
180
|
-
| Header
|
|
181
|
-
|
|
|
182
|
-
| `X-BW-Host`
|
|
183
|
-
| `X-BW-Password`
|
|
184
|
-
| `X-BW-ClientId`
|
|
185
|
-
| `X-BW-ClientSecret`
|
|
186
|
-
| `X-BW-User` or `X-BW-Username` | username/email alternative to API key login
|
|
187
|
-
| `X-BW-Unlock-Interval`
|
|
179
|
+
| Header | Meaning |
|
|
180
|
+
| ------------------------------ | ---------------------------------------------------------------- |
|
|
181
|
+
| `X-BW-Host` | HTTPS origin only, for example `https://vaultwarden.example.com` |
|
|
182
|
+
| `X-BW-Password` | master password used to unlock the vault |
|
|
183
|
+
| `X-BW-ClientId` | Bitwarden API key client id |
|
|
184
|
+
| `X-BW-ClientSecret` | Bitwarden API key client secret |
|
|
185
|
+
| `X-BW-User` or `X-BW-Username` | username/email alternative to API key login |
|
|
186
|
+
| `X-BW-Unlock-Interval` | optional unlock interval in seconds; default `300` |
|
|
188
187
|
|
|
189
188
|
Example HTTP MCP config for hosts that support custom headers:
|
|
190
189
|
|
|
@@ -246,12 +245,11 @@ default. If you use a bind mount, make it writable by uid/gid `1000`.
|
|
|
246
245
|
The Docker image includes the supported Node runtime.
|
|
247
246
|
|
|
248
247
|
The server resolves `bw` in this order:
|
|
249
|
-
|
|
250
248
|
1. `BW_BIN`, when set
|
|
251
249
|
2. bundled `@bitwarden/cli` dependency
|
|
252
250
|
3. system `bw` from `PATH`
|
|
253
251
|
|
|
254
|
-
The bundled `@bitwarden/cli` version is currently `2026.
|
|
252
|
+
The bundled `@bitwarden/cli` version is currently `2026.10.0`. This project keeps
|
|
255
253
|
that version vetted instead of blindly tracking every upstream release, because
|
|
256
254
|
auth and unlock behavior can change in ways that break automation.
|
|
257
255
|
|
|
@@ -259,7 +257,7 @@ If `bw` is missing, install the CLI explicitly or point `BW_BIN` to a known
|
|
|
259
257
|
binary:
|
|
260
258
|
|
|
261
259
|
```bash
|
|
262
|
-
npm install -g @bitwarden/cli@2026.
|
|
260
|
+
npm install -g @bitwarden/cli@2026.10.0
|
|
263
261
|
BW_BIN=/absolute/path/to/bw npx -y @icoretech/warden-mcp@latest --stdio
|
|
264
262
|
```
|
|
265
263
|
|
|
@@ -267,7 +265,6 @@ BW_BIN=/absolute/path/to/bw npx -y @icoretech/warden-mcp@latest --stdio
|
|
|
267
265
|
|
|
268
266
|
There is no built-in authentication layer in v1. Protect the transport before
|
|
269
267
|
you expose it.
|
|
270
|
-
|
|
271
268
|
- **Bind locally by default** - use `WARDEN_MCP_HOST=127.0.0.1`, Docker
|
|
272
269
|
`-p 127.0.0.1:3005:3005`, a firewall, VPN, or an authenticated reverse proxy
|
|
273
270
|
- **Use TLS for HTTP mode** - `X-BW-*` headers carry vault credentials
|
|
@@ -294,25 +291,25 @@ Returning notes or private keys requires `reveal: true`; `NOREVEAL` and
|
|
|
294
291
|
|
|
295
292
|
## Configuration
|
|
296
293
|
|
|
297
|
-
| Variable
|
|
298
|
-
|
|
|
299
|
-
| `PORT`
|
|
300
|
-
| `WARDEN_MCP_HOST`
|
|
301
|
-
| `WARDEN_MCP_STDIO`
|
|
302
|
-
| `MCP_APP_NAME`
|
|
303
|
-
| `TOOL_PREFIX`
|
|
304
|
-
| `TOOL_SEPARATOR`
|
|
305
|
-
| `KEYCHAIN_BW_HOME_ROOT`
|
|
306
|
-
| `KEYCHAIN_ALLOW_ENV_FALLBACK`
|
|
307
|
-
| `KEYCHAIN_SYNC_ON_WRITE`
|
|
308
|
-
| `READONLY` / `KEYCHAIN_READONLY`
|
|
309
|
-
| `NOREVEAL` / `KEYCHAIN_NOREVEAL`
|
|
310
|
-
| `KEYCHAIN_TEXT_COMPAT_MODE`
|
|
311
|
-
| `KEYCHAIN_SESSION_MAX_COUNT`
|
|
312
|
-
| `KEYCHAIN_SESSION_TTL_MS`
|
|
313
|
-
| `KEYCHAIN_SESSION_SWEEP_INTERVAL_MS` | `60000`
|
|
314
|
-
| `KEYCHAIN_MAX_HEAP_USED_MB`
|
|
315
|
-
| `KEYCHAIN_METRICS_LOG_INTERVAL_MS`
|
|
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 |
|
|
316
313
|
|
|
317
314
|
`KEYCHAIN_TEXT_COMPAT_MODE=structured_json` mirrors supported
|
|
318
315
|
`structuredContent` into plain text. That helps MCP clients that only pass
|
|
@@ -325,7 +322,6 @@ Tool names default to `keychain_*`. Change the prefix with `TOOL_PREFIX` and the
|
|
|
325
322
|
separator with `TOOL_SEPARATOR`.
|
|
326
323
|
|
|
327
324
|
Start with these:
|
|
328
|
-
|
|
329
325
|
- `keychain_status` - inspect raw `bw` status
|
|
330
326
|
- `keychain_sync` - pull latest vault data with `bw sync`
|
|
331
327
|
- `keychain_search_items` - find items by name, URI, username, folder,
|
|
@@ -338,18 +334,17 @@ Start with these:
|
|
|
338
334
|
|
|
339
335
|
Full tool groups:
|
|
340
336
|
|
|
341
|
-
| Group
|
|
342
|
-
|
|
|
343
|
-
| Vault/session
|
|
344
|
-
| Items
|
|
345
|
-
| Folders
|
|
346
|
-
| 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`
|
|
347
|
-
| Attachments
|
|
348
|
-
| Sends
|
|
349
|
-
| Direct `bw get` helpers
|
|
337
|
+
| Group | Tools |
|
|
338
|
+
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
339
|
+
| Vault/session | `keychain_status`, `keychain_sync`, `keychain_sdk_version`, `keychain_encode`, `keychain_generate`, `keychain_generate_username` |
|
|
340
|
+
| 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` |
|
|
341
|
+
| Folders | `keychain_list_folders`, `keychain_create_folder`, `keychain_edit_folder`, `keychain_delete_folder` |
|
|
342
|
+
| 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` |
|
|
343
|
+
| Attachments | `keychain_create_attachment`, `keychain_delete_attachment`, `keychain_get_attachment` |
|
|
344
|
+
| 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` |
|
|
345
|
+
| 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` |
|
|
350
346
|
|
|
351
347
|
Notes:
|
|
352
|
-
|
|
353
348
|
- `keychain_create_logins` creates several independent login items in one call
|
|
354
349
|
and reports per-item failures without aborting the whole batch
|
|
355
350
|
- `keychain_set_login_uris` replaces or merges a login item's URI list without
|
|
@@ -379,18 +374,18 @@ account, and runs the MCP server in the foreground.
|
|
|
379
374
|
|
|
380
375
|
Useful commands:
|
|
381
376
|
|
|
382
|
-
| Command
|
|
383
|
-
|
|
|
384
|
-
| `npm run dev`
|
|
385
|
-
| `npm run build`
|
|
386
|
-
| `npm run start`
|
|
387
|
-
| `npm run lint`
|
|
388
|
-
| `npm run test`
|
|
389
|
-
| `npm run test:integration` | build, then run compose-backed integration tests
|
|
390
|
-
| `npm run test:coverage`
|
|
391
|
-
| `make test`
|
|
392
|
-
| `make test-org`
|
|
393
|
-
| `make down`
|
|
377
|
+
| Command | Purpose |
|
|
378
|
+
| -------------------------- | --------------------------------------------------- |
|
|
379
|
+
| `npm run dev` | watch-mode server from source |
|
|
380
|
+
| `npm run build` | compile TypeScript to `dist/` |
|
|
381
|
+
| `npm run start` | run the compiled server |
|
|
382
|
+
| `npm run lint` | Biome autofix plus `tsc --noEmit` |
|
|
383
|
+
| `npm run test` | build, then run all compiled tests |
|
|
384
|
+
| `npm run test:integration` | build, then run compose-backed integration tests |
|
|
385
|
+
| `npm run test:coverage` | build, then run Node test coverage |
|
|
386
|
+
| `make test` | run the compose-backed Vaultwarden integration path |
|
|
387
|
+
| `make test-org` | run the organization-focused compose stack |
|
|
388
|
+
| `make down` | stop the local compose stack |
|
|
394
389
|
|
|
395
390
|
For a quick live MCP smoke against local Vaultwarden, see
|
|
396
391
|
[agent-instructions/testing.md](agent-instructions/testing.md).
|
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.55",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",
|
|
@@ -39,12 +39,12 @@
|
|
|
39
39
|
"start": "node dist/server.js",
|
|
40
40
|
"test": "npm run build && node --test \"dist/**/*.test.js\"",
|
|
41
41
|
"test:coverage": "npm run build && node --test --experimental-test-coverage \"dist/**/*.test.js\"",
|
|
42
|
-
"test:integration": "npm run build && node --test --test-concurrency=1 --test-timeout=
|
|
42
|
+
"test:integration": "npm run build && node --test --test-concurrency=1 --test-timeout=360000 \"dist/integration/**/*.test.js\"",
|
|
43
43
|
"test:session-regression": "node scripts/session-flood-regression.mjs",
|
|
44
44
|
"lint": "biome check --write --assist-enabled=true . && tsc --noEmit"
|
|
45
45
|
},
|
|
46
46
|
"dependencies": {
|
|
47
|
-
"@bitwarden/cli": "2026.
|
|
47
|
+
"@bitwarden/cli": "2026.10.0",
|
|
48
48
|
"@modelcontextprotocol/sdk": "^1.32.1",
|
|
49
49
|
"express": "^5.3.0",
|
|
50
50
|
"zod": "^4.6.7"
|
|
@@ -55,10 +55,10 @@
|
|
|
55
55
|
"tmp": "0.2.7"
|
|
56
56
|
},
|
|
57
57
|
"devDependencies": {
|
|
58
|
-
"@biomejs/biome": "
|
|
58
|
+
"@biomejs/biome": "2.6.2",
|
|
59
59
|
"@types/express": "^5.0.6",
|
|
60
60
|
"@types/node": "^22.20.5",
|
|
61
|
-
"playwright": "1.
|
|
61
|
+
"playwright": "1.64.1",
|
|
62
62
|
"tsx": "^4.23.15",
|
|
63
63
|
"typescript": "^7.0.2"
|
|
64
64
|
},
|
|
@@ -67,7 +67,7 @@
|
|
|
67
67
|
"access": "public"
|
|
68
68
|
},
|
|
69
69
|
"engines": {
|
|
70
|
-
"node": "~22.23.
|
|
70
|
+
"node": "~22.23.4",
|
|
71
71
|
"npm": "~10.9.9"
|
|
72
72
|
}
|
|
73
73
|
}
|