MCP Vaultwarden Connector

🔐 MCP Vaultwarden Server

Un serveur MCP (Model-Context-Protocol) qui expose une interface simple et robuste pour interagir avec une instance Vaultwarden auto-hébergée. Il agit comme un wrapper autour de la CLI officielle de Bitwarden (bw), permettant à des agents IA ou des scripts d'automatisation de gérer des secrets de manière programmatique.

🤔 Pourquoi ce projet ?

Vaultwarden est une alternative populaire et légère à Bitwarden, mais son automatisation peut être complexe. La CLI officielle (bw) nécessite une gestion manuelle de la session (login, unlock, etc.), ce qui n'est pas idéal pour une utilisation par des agents IA ou dans des scripts non-interactifs.

Ce MCP résout ce problème en :

• Gérant automatiquement la session : Il déverrouille le coffre à la demande et maintient la session active en cache.
• Exposant des outils simples : Fournit des fonctions claires (get_secret, list_secrets, etc.) via le protocole MCP.
• Prévenant les blocages : Intègre des timeouts et un système de verrouillage pour gérer les accès concurrents de manière fiable.

✨ Fonctionnalités

• Auto-déverrouillage : Le coffre est déverrouillé à la première requête et la clé de session est mise en cache.
• Gestion des Conflits : Un mécanisme de "lock" empêche les déverrouillages multiples et concurrents.
• API Complète : Supporte la lecture, la création, la mise à jour et la suppression de secrets.
• Modèles de Secrets : Fournit des templates JSON pour créer de nouveaux éléments facilement.
• Sécurité : S'appuie sur la CLI bw officielle pour toutes les opérations cryptographiques.

---

⚠️ Prérequis

Pour que ce serveur fonctionne, la machine qui l'exécute doit avoir la CLI Bitwarden (bw) installée et accessible dans le PATH.

Suivez les instructions d'installation officielles : Installer la CLI Bitwarden.

---

📦 Installation

Méthode 1 : Via NPM (Recommandé)

C'est la méthode la plus simple pour une utilisation avec un client MCP comme gemini-cli.

Configurez votre client pour qu'il lance le serveur via 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éthode 2 : Depuis les Sources (Git)

1. Clonez le dépôt :

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

2. Installez les dépendances :

   npm install
   

3. Configurez et lancez : Créez un fichier .env à partir de .env.example et remplissez-le, puis lancez le serveur.

   cp .env.example .env
   nano .env
   node server.js
   

---

🔒 Configuration & Sécurité

La configuration se fait via des variables d'environnement.

• BITWARDEN_HOST: L'URL de votre instance Vaultwarden.
• BW_CLIENTID: Votre Client ID d'API.
• BW_CLIENTSECRET: Votre Client Secret d'API.
• BW_MASTER_PASSWORD: Votre mot de passe principal.

AVERTISSEMENT DE SÉCURITÉ : La gestion du BW_MASTER_PASSWORD est critique.

• Ne jamais commiter votre fichier .env ou vos secrets dans un dépôt Git.
• Pour une utilisation en production, préférez des méthodes de gestion de secrets plus robustes, comme les secrets de votre orchestrateur (Kubernetes Secrets, Docker Secrets) ou un service dédié (HashiCorp Vault).
• Ce MCP est conçu pour être exécuté dans un environnement contrôlé et sécurisé.

---

🧰 Référence des Outils (API)

Voici les outils exposés par ce MCP, avec des exemples d'appels.

get_secret

Récupère un secret par son nom ou son ID.

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

list_secrets

Recherche des secrets contenant un terme.

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

get_secret_template

Obtient un modèle JSON pour créer un nouveau secret.

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

Types valides : login, note, card, identity.

create_secret

Crée un nouvel élément. Utilisez d'abord 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\\\"}]}}"
  }
}

Note : Le JSON doit être une chaîne de caractères échappée.

update_secret

Met à jour un secret existant par son ID.

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

delete_secret

Supprime un secret par son ID.

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

sync

Force la synchronisation du coffre local avec le serveur distant.

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

---

🤝 Contribution

Les contributions sont les bienvenues ! N'hésitez pas à forker le projet et à ouvrir une Pull Request.

📝 Licence

MIT