README.md•5.97 kB
# 🔐 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/VOTRE_NOM/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