MCP Vaultwarden Server

# 🔐 MCP Vaultwarden Server [](https://www.npmjs.com/package/mcp-vaultwarden-server) [](LICENSE) [](https://nodejs.org) 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](https://bitwarden.com/help/cli/). --- ## 📦 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` : ```json { "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 :** ```bash git clone https://github.com/fkom13/mcp-vaultwarden.git cd mcp-vaultwarden ``` 2. **Installez les dépendances :** ```bash npm install ``` 3. **Configurez et lancez :** Créez un fichier `.env` à partir de `.env.example` et remplissez-le, puis lancez le serveur. ```bash 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. ```json { "tool": "get_secret", "arguments": { "name": "API Key - OpenAI" } } ``` ### `list_secrets` Recherche des secrets contenant un terme. ```json { "tool": "list_secrets", "arguments": { "search_term": "database" } } ``` ### `get_secret_template` Obtient un modèle JSON pour créer un nouveau secret. ```json { "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`. ```json { "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. ```json { "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. ```json { "tool": "delete_secret", "arguments": { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } } ``` ### `sync` Force la synchronisation du coffre local avec le serveur distant. ```json { "tool": "sync", "arguments": {} } ``` --- ## 🤝 Contribution Les contributions sont les bienvenues ! N'hésitez pas à forker le projet et à ouvrir une Pull Request. ## 📝 Licence MIT