MCP Vaultwarden Connector

Proporciona un puente para que scripts y agentes de IA interactúen con una instancia autoalojada de Vaultwarden.

Documentación

🔐 MCP Vaultwarden Server

Un servidor MCP (Model-Context-Protocol) que expone una interfaz simple y robusta para interactuar con una instancia Vaultwarden autoalojada. Actúa como un envoltorio alrededor de la CLI oficial de Bitwarden (bw), permitiendo a agentes de IA o scripts de automatización gestionar secretos de manera programática.

🤔 ¿Por qué este proyecto?

Vaultwarden es una alternativa popular y ligera a Bitwarden, pero su automatización puede ser compleja. La CLI oficial (bw) requiere una gestión manual de la sesión (login, unlock, etc.), lo que no es ideal para su uso por agentes de IA o en scripts no interactivos.

Este MCP resuelve este problema al:

Gestionando automáticamente la sesión: Desbloquea la bóveda bajo demanda y mantiene la sesión activa en caché.
Exponiendo herramientas simples: Proporciona funciones claras (get_secret, list_secrets, etc.) a través del protocolo MCP.
Previniendo bloqueos: Integra timeouts y un sistema de bloqueo para gestionar accesos concurrentes de manera fiable.

✨ Características

Auto-desbloqueo: La bóveda se desbloquea en la primera solicitud y la clave de sesión se guarda en caché.
Gestión de Conflictos: Un mecanismo de "lock" evita desbloqueos múltiples y concurrentes.
API Completa: Soporta la lectura, creación, actualización y eliminación de secretos.
Modelos de Secretos: Proporciona plantillas JSON para crear nuevos elementos fácilmente.
Seguridad: Se basa en la CLI bw oficial para todas las operaciones criptográficas.

⚠️ Requisitos previos

Para que este servidor funcione, la máquina que lo ejecuta debe tener la CLI de Bitwarden (bw) instalada y accesible en el PATH.

Siga las instrucciones de instalación oficiales: Instalar la CLI de Bitwarden.

📦 Instalación

Método 1: Vía NPM (Recomendado)

Es el método más simple para su uso con un cliente MCP como gemini-cli.

Configure su cliente para que inicie el servidor a través de npx:

{
  "mcpServers": {
    "vaultwarden": {
      "command": "npx",
      "args": [
        "mcp-vaultwarden-server"
      ],
      "env": {
        "BITWARDEN_HOST": "https://votre-instance.vaultwarden.com",
        "BW_CLIENTID": "user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "BW_CLIENTSECRET": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "BW_MASTER_PASSWORD": "votre-mot-de-passe-maitre"
      }
    }
  }
}

Método 2: Desde las Fuentes (Git)

Clone el repositorio:

git clone https://github.com/fkom13/mcp-vaultwarden.git
cd mcp-vaultwarden

Instale las dependencias:
```
npm install
```
Configure y ejecute: Cree un archivo .env a partir de .env.example y complételo, luego ejecute el servidor.
```
cp .env.example .env
nano .env
node server.js
```

🔒 Configuración y Seguridad

La configuración se realiza mediante variables de entorno.

BITWARDEN_HOST: La URL de su instancia de Vaultwarden.
BW_CLIENTID: Su Client ID de API.
BW_CLIENTSECRET: Su Client Secret de API.
BW_MASTER_PASSWORD: Su contraseña maestra.

ADVERTENCIA DE SEGURIDAD: La gestión del BW_MASTER_PASSWORD es crítica.

Nunca haga commit de su archivo .env o sus secretos en un repositorio Git.
Para uso en producción, prefiera métodos de gestión de secretos más robustos, como los secretos de su orquestador (Kubernetes Secrets, Docker Secrets) o un servicio dedicado (HashiCorp Vault).
Este MCP está diseñado para ejecutarse en un entorno controlado y seguro.

🧰 Referencia de Herramientas (API)

Aquí están las herramientas expuestas por este MCP, con ejemplos de llamadas.

`get_secret`

Recupera un secreto por su nombre o ID.

{
  "tool": "get_secret",
  "arguments": {
    "name": "API Key - OpenAI"
  }
}

`list_secrets`

Busca secretos que contengan un término.

{
  "tool": "list_secrets",
  "arguments": {
    "search_term": "database"
  }
}

`get_secret_template`

Obtiene un modelo JSON para crear un nuevo secreto.

{
  "tool": "get_secret_template",
  "arguments": {
    "type": "login"
  }
}

Tipos válidos: login, note, card, identity.

`create_secret`

Crea un nuevo elemento. Use primero get_secret_template.

{
  "tool": "create_secret",
  "arguments": {
    "item_json": "{\\\"type\\\":1,\\\"name\\\":\\\"Mon Nouveau Login\\\",\\\"notes\\\":\\\"Ceci est une note secrète.\\\",\\\"favorite\\\":false,\\\"login\\\":{\\\"username\\\":\\\"monuser\\\",\\\"password\\\":\\\"MonP@ssw0rd!\\\",\\\"uris\\\":[{\\\"uri\\\":\\\"https://example.com\\\"}]}}"
  }
}

Nota: El JSON debe ser una cadena de caracteres escapada.

`update_secret`

Actualiza un secreto existente por su ID.

{
  "tool": "update_secret",
  "arguments": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "item_json": "{\\\"name\\\":\\\"Ancien Login (Mis à jour)\\\"}"
  }
}

`delete_secret`

Elimina un secreto por su ID.

{
  "tool": "delete_secret",
  "arguments": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

`sync`

Fuerza la sincronización de la bóveda local con el servidor remoto.

{
  "tool": "sync",
  "arguments": {}
}

🤝 Contribución

¡Las contribuciones son bienvenidas! No dude en hacer fork del proyecto y abrir una Pull Request.

📝 Licencia

MIT