bitwarden / bitwarden/mcp-server
CLI-backed tools hang indefinitely when the vault is locked
- Dominant language
- TypeScript
- Stars
- 254
- Forks
- 34
- Avg merge
- 20h 45m
- Merged PRs (30d)
- 1
Description
### Steps to reproduce
1. Configure the MCP server to use the Bitwarden CLI without setting `BW_SESSION`.
2. Start the server while `bw status` reports `"status":"locked"`.
3. Invoke a CLI-backed tool such as `list` or `create_item`.
### Actual behavior
The tool call never returns. The MCP client eventually has to interrupt it. Calling the dedicated `unlock` tool and completing the native password prompt makes subsequent calls return normally.
I reproduced this with:
- `@bitwarden/mcp-server` 2026.7.0
- Bitwarden CLI 2026.7.0
- macOS
- stdio transport
This happened consistently with both `list` and `create_item`.
### Expected behavior
CLI-backed tools should fail quickly with an actionable error such as:
> Vault is locked. Call the `unlock` tool before retrying.
A timeout should also prevent a stalled `bw` child process from leaving an MCP request pending indefinitely.
### Additional context
Issue #176 described the broader problem as “everything stalls” when a session expires and introduced the safe out-of-band `unlock` tool. That solves recovery once the user knows the vault is locked, but ordinary tools still appear to hang instead of directing the user to it.
The current `executeCliCommand` implementation spawns `bw` and resolves on `error` or `close`, but does not appear to perform a locked-vault preflight or enforce a child-process timeout. A status check before commands requiring an unlocked vault, plus a bounded timeout, would make this failure mode explicit and recoverable.
Contributor guide
Research direction
Start with the current executeCliCommand implementation and reproduce the issue with BW_SESSION unset while bw reports the vault as locked. Add coverage for locked-vault failures and stalled child processes; done means list and create_item return an actionable unlock error or timeout instead of leaving the MCP request pending.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend, cli
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100