Vaultwarden-MCP

Un servidor MCP alojado localmente para interacciones entre Claude y una instancia de Vaultwarden alojada, utilizando la CLI.

GitHub

Documentación

Vaultwarden MCP: conecta Claude a tu bóveda de contraseñas autohospedada

Un servidor MCP que le da a Claude acceso a una bóveda Vaultwarden o Bitwarden autohospedada a través de la CLI oficial de Bitwarden. Busca tus inicios de sesión, consúltalos, añade nuevos y edítalos, desde una ventana de chat.

Claude nunca recibe una contraseña. No puede cambiar nada sin que tú hagas clic en Guardar.

Vaultwarden MCP inline card showing a GitHub login: username, hidden password with reveal and copy buttons, one-time code, site, and notes. Vault status card in dark mode showing the vault unlocked, the instance address, and when it last synced.

No está afiliado con Bitwarden ni Vaultwarden. Este es un proyecto personal que utiliza la CLI publicada de Bitwarden. Lee SECURITY.md antes de apuntarlo a una bóveda que te importe.

Contenido · Qué hace · Instalación · Compatibilidad · Configuración · Herramientas · Solución de problemas · Seguridad

Qué hace

Pide un inicio de sesión y aparece una tarjeta junto a la respuesta, con la contraseña oculta detrás de una fila de puntos con un botón de copiar al lado. Pide uno nuevo y obtienes un borrador completado con una contraseña generada que se guarda cuando presionas Guardar, y no antes.

Claude puede	Claude no puede
Buscar en la bóveda y listar carpetas	Leer una contraseña, código de un solo uso o nota, a menos que lo apruebes en una ventana de escritorio, una vez por solicitud
Ver nombres de elementos, nombres de usuario y sitios	Crear, editar o eliminar cualquier cosa hasta que presiones Guardar o Confirmar en la tarjeta
Ver si un elemento tiene contraseña, código o notas	Eliminar permanentemente. Las eliminaciones van a la papelera, donde tu servidor las conserva 30 días
Generar una contraseña en la tarjeta	Cambiar qué servidor de bóveda se usa. Eso se fija en la instalación
Preparar cambios para que los confirmes	Ver tu contraseña maestra. La escribes en una ventana de escritorio

SECURITY.md explica por qué cada línea está trazada donde está.

La tarjeta

New login draft card with name, username, site, a generated password with strength meter, folder picker, and Save and Cancel buttons. Confirmation card showing the old username struck through beside the new one. Trash confirmation card noting that the server keeps trashed items for 30 days.

Cualquier cosa sensible ocurre aquí en lugar de en la conversación. La tarjeta sigue los temas claros y oscuros de Claude.

Revelar muestra un secreto durante treinta segundos y luego lo oculta. Copiar nunca lo muestra: el servidor escribe el valor directamente en tu portapapeles y lo borra treinta segundos después, etiquetado para que el historial del portapapeles de Windows y el portapapeles en la nube lo omitan. Los elementos que marcaste como "solicitar contraseña maestra de nuevo" piden tu contraseña nuevamente antes de cualquiera de las dos acciones.

Los iconos de sitios provienen del servicio de iconos de tu propia instancia, el mismo que usa la bóveda web. Esa es la única origen desde la que la tarjeta puede cargar algo. Los elementos sin icono muestran su inicial en su lugar.

Instalación

Claude Desktop, desde una versión publicada

Descarga vaultwarden-mcp-<version>.mcpb desde la última versión.
Haz doble clic en él. Claude Desktop lo instala como una extensión.
Ingresa la dirección de tu bóveda, como https://vault.example.com. Todo lo demás es opcional.
Pide a Claude que inicie sesión en tu bóveda. Se abre una ventana en tu escritorio para tu correo electrónico, contraseña maestra y código de dos pasos si usas uno.

No hay nada más que instalar. La CLI de Bitwarden viaja dentro del paquete.

Claude Desktop, desde el código fuente

git clone https://github.com/ShadowsDistant/Vaultwarden-MCP.git
cd Vaultwarden-MCP
npm install --legacy-peer-deps
npm run build
node scripts/install.mjs --server https://vault.example.com --email you@example.com

Luego cierra Claude Desktop por completo y vuelve a abrirlo.

En Windows, usa scripts\setup.ps1 en su lugar. Se compila en %USERPROFILE%\.vaultwarden-mcp, lo cual importa si clonaste en una carpeta de OneDrive:

.\scripts\setup.ps1 -Install -Server https://vault.example.com -Email you@example.com

Claude Code

claude mcp add vaultwarden --env VW_MCP_SERVER_URL=https://vault.example.com -- node /path/to/Vaultwarden-MCP/dist/index.js

Cualquier otro cliente MCP

El servidor habla MCP sobre stdio, así que cualquier cosa que pueda lanzar un servidor stdio puede ejecutarlo. Apunta la configuración de tu cliente al punto de entrada compilado:

{
  "mcpServers": {
    "vaultwarden": {
      "command": "node",
      "args": ["/path/to/Vaultwarden-MCP/dist/index.js"],
      "env": {
        "VW_MCP_SERVER_URL": "https://vault.example.com",
        "VW_MCP_EMAIL": "you@example.com"
      }
    }
  }
}

En Windows, da la ruta completa a node.exe y escapa las barras invertidas en las rutas.

Iniciar sesión

Pide a Claude que inicie sesión. La ventana que se abre pertenece a este servidor, no a Claude, y lo que escribes va por una tubería a la CLI de Bitwarden sin pasar por la conversación.

Si algo alguna vez pide tu contraseña maestra dentro del chat, no es este servidor.

Compatibilidad


Node	20 o más reciente. La CLI de Bitwarden está incluida.
Bóveda	Vaultwarden 1.37.2 o más reciente, o el servicio alojado de Bitwarden.
Windows	Soporte completo. Las ventanas de inicio de sesión y confirmación usan WPF.
macOS	Soporte completo, usando `osascript` para ventanas.
Linux	Necesita `zenity` o `kdialog` para las ventanas. Sin uno, desbloquea la bóveda tú mismo y pasa `BW_SESSION`.
Tarjetas integradas	Necesitan un host que implemente la extensión MCP Apps. Claude Desktop y Claude Code lo hacen.
Otros clientes MCP	Las herramientas funcionan en cualquier lugar. Sin soporte de tarjetas, las herramientas solo de tarjeta nunca se registran, y las revelaciones y confirmaciones recurren a ventanas de escritorio.

Una máquina sin interfaz gráfica aún puede ejecutar el servidor: desbloquea la bóveda tú mismo con bw unlock --raw y inícialo con BW_SESSION configurado.

Configuración

Configúralos en la configuración de la extensión en Claude Desktop, o como variables de entorno en la configuración de tu cliente.

Variable	Predeterminado	Qué hace
`VW_MCP_SERVER_URL`	requerido	La dirección de tu bóveda. Deliberadamente no se puede configurar desde una conversación.
`VW_MCP_EMAIL`	ninguno	Rellena previamente la ventana de inicio de sesión.
`VW_MCP_IDLE_LOCK_MIN`	`0`	También bloquea después de esta cantidad de minutos de inactividad. `0` bloquea solo cuando la aplicación se cierra.
`VW_MCP_MODEL_REVEAL`	`ask`	`ask` permite que Claude solicite un secreto a la vez, con una ventana que debes aprobar. `off` rechaza directamente.
`VW_MCP_HOME`	`~/.vaultwarden-mcp`	Dónde viven la caché de la bóveda, la configuración y el registro.
`VW_MCP_CA_FILE`	ninguno	Un paquete de CA, si tu instancia usa una autoridad de certificación privada.
`VW_MCP_ALLOW_HTTP`	sin configurar	Permitir una dirección http simple para un host distinto de localhost.
`VW_MCP_REVEAL_SECONDS`	`30`	Cuánto tiempo permanece visible un secreto revelado en pantalla.
`VW_MCP_CLIPBOARD_CLEAR_SECONDS`	`30`	Cuánto tiempo permanece un secreto copiado en el portapapeles.
`BW_SESSION`	sin configurar	Una sesión ya desbloqueada, para una máquina sin escritorio.

Herramientas

⧉ marca las herramientas que dibujan una tarjeta.

Herramienta	Qué hace
`vault_status` ⧉	Si la bóveda está con sesión iniciada, bloqueada o desbloqueada, y qué instancia usa
`vault_login` ⧉	Iniciar sesión, en una ventana en tu escritorio
`vault_unlock` ⧉	Desbloquear, en una ventana en tu escritorio, luego mostrar la bóveda
`vault_lock`	Bloquear inmediatamente y olvidar la clave de sesión
`vault_sync`	Obtener el contenido más reciente del servidor
`vault_search` ⧉	Encontrar elementos por nombre, sitio o carpeta. Solo nombres y hosts, sin nombres de usuario en masa
`vault_get_item` ⧉	Un elemento completo, menos todos los secretos
`vault_list_folders`	Las carpetas, con los ids usados para archivar o filtrar
`vault_generate_password` ⧉	Generar una contraseña o frase de contraseña en la tarjeta, no en la conversación
`vault_create_login` ⧉	Preparar un nuevo inicio de sesión para que lo guardes
`vault_edit_item` ⧉	Preparar un cambio para que lo confirmes, mostrado como antes y después
`vault_trash_item` ⧉	Preparar mover un elemento a la papelera, para que lo confirmes
`vault_restore_item` ⧉	Traer un elemento de vuelta de la papelera
`vault_reveal_secret`	Preguntarte, en una ventana de escritorio, que liberes un secreto en la conversación

Un segundo conjunto de herramientas sirve solo a la tarjeta: leer un secreto con un clic, copiar al portapapeles, guardar un borrador. Están marcadas como solo de aplicación y permanecen sin registrar a menos que el cliente declare soporte de MCP Apps al inicio, así que en cualquier otro host no existen y nada puede llamarlas.

Solución de problemas

"La CLI de Bitwarden no está instalada." La CLI incluida no sobrevivió a la instalación. Vuelve a ejecutar npm install --legacy-peer-deps y npm run build, o reinstala la extensión.

No aparece ninguna ventana al iniciar sesión. En Linux, instala zenity o kdialog. En otros lugares, revisa ~/.vaultwarden-mcp/logs/server.log. Como alternativa, ejecuta bw unlock --raw tú mismo y pasa el resultado como BW_SESSION.

"No se pudo alcanzar el servidor de la bóveda." Revisa la dirección en tu configuración y que la instancia esté activa. Para una autoridad de certificación privada, apunta VW_MCP_CA_FILE al paquete.

Claude dice que se creó un elemento pero no está allí. Era un borrador, y los borradores no se escriben hasta que presionas Guardar. Si no apareció ninguna tarjeta, tu host no soporta MCP Apps.

La bóveda se bloquea constantemente. Por defecto permanece abierta hasta que la aplicación se cierra. Si configuraste VW_MCP_IDLE_LOCK_MIN, súbelo o vuelve a configurarlo a 0.

Desarrollo

npm install --legacy-peer-deps
npm run build     # tsc, then bundle the card into a single HTML file
npm test          # 81 tests against a fake Bitwarden CLI, over real stdio
npm run preview   # card views at http://localhost:8766, plus /selftest.html
npm run pack      # build the .mcpb extension bundle

Ninguna prueba toca una bóveda real. test/fake-bw/bw.js emula la CLI, coincidiendo con sus sobres --response y reproduciendo dos de sus errores incluidos, y el servidor se ejecuta como un proceso hijo real impulsado por el cliente del SDK de MCP. La prueba de carga coloca una cadena centinela en cada secreto y falla si aparece en cualquier lugar donde un modelo podría leer.

src/index.ts      server bootstrap, instructions, shutdown
src/config.ts     settings, paths, URL validation
src/bw.ts         CLI wrapper: re-entrant lock, minimal environment, response parsing
src/session.ts    the session key, sign-in, unlock, idle lock
src/vault.ts      item operations, and the model-facing and card-facing projections
src/sanitize.ts   the untrusted-text screen and the result envelope
src/pending.ts    staged changes: unguessable ids, single use, ten-minute lifetime
src/prompt.ts     native dialogs
src/clipboard.ts  copy, and the clear that only fires if the value is still there
src/tools.ts      the tool surface
ui/card.html      the card's markup and theme
ui/card.ts        the card
scripts/          build, install, package, dialog and clipboard helpers
test/             unit tests, end-to-end tests, the fake CLI and dialog

Licencia

Este programa es software libre: puedes redistribuirlo y modificarlo bajo los términos de la GNU General Public License publicada por la Free Software Foundation, ya sea la versión 3 de la Licencia, o (a tu elección) cualquier versión posterior. Se distribuye sin ninguna garantía, sin siquiera la garantía implícita de comerciabilidad o idoneidad para un propósito particular. Consulta la GNU General Public License para más detalles.

La CLI de Bitwarden incluida se redistribuye bajo sus propios términos.