bitwarden / bitwarden/mcp-server

CLI-backed tools hang indefinitely when the vault is locked

Open
#231 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.