MCP Vaultwarden Server

Un serveur MCP (Model-Context-Protocol) qui expose une interface simple et robuste pour interagir avec une instance Vaultwarden auto-hberge. Il agit comme un wrapper autour de la CLI officielle de Bitwarden (bw), permettant des agents IA ou des scripts d'automatisation de grer des secrets de manire programmatique.

Pourquoi ce projet ?

Vaultwarden est une alternative populaire et lgre Bitwarden, mais son automatisation peut tre complexe. La CLI officielle (bw) ncessite une gestion manuelle de la session (login, unlock, etc.), ce qui n'est pas idal pour une utilisation par des agents IA ou dans des scripts non-interactifs.

Ce MCP rsout ce problme en :

• Grant automatiquement la session : Il dverrouille 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.
• Prvenant les blocages : Intgre des timeouts et un systme de verrouillage pour grer les accs concurrents de manire fiable.

Fonctionnalits

• Auto-dverrouillage : Le coffre est dverrouill la premire requte et la cl de session est mise en cache.
• Gestion des Conflits : Un mcanisme de "lock" empche les dverrouillages multiples et concurrents.
• API Complte : Supporte la lecture, la cration, la mise jour et la suppression de secrets.
• Modles de Secrets : Fournit des templates JSON pour crer de nouveaux lments facilement.
• Scurit : S'appuie sur la CLI bw officielle pour toutes les oprations cryptographiques.

Prrequis

Pour que ce serveur fonctionne, la machine qui l'excute doit avoir la CLI Bitwarden (bw) installe et accessible dans le PATH.

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

Installation

Mthode 1 : Via NPM (Recommand)

C'est la mthode 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"
      }
    }
  }
}

Mthode 2 : Depuis les Sources (Git)

1. Clonez le dpt :

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

2. Installez les dpendances :

   npm install
   

3. Configurez et lancez :
   Crez un fichier .env partir de .env.example et remplissez-le, puis lancez le serveur.

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

Configuration & Scurit

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 SCURIT :
La gestion du BW_MASTER_PASSWORD est critique.

• Ne jamais commiter votre fichier .env ou vos secrets dans un dpt Git.
• Pour une utilisation en production, prfrez des mthodes de gestion de secrets plus robustes, comme les secrets de votre orchestrateur (Kubernetes Secrets, Docker Secrets) ou un service ddi (HashiCorp Vault).
• Ce MCP est conu pour tre excut dans un environnement contrl et scuris.

Rfrence des Outils (API)

Voici les outils exposs par ce MCP, avec des exemples d'appels.

get_secret

Rcupre 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 modle JSON pour crer un nouveau secret.

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

Types valides : login, note, card, identity.

create_secret

Cre un nouvel lment. Utilisez d'abord get_secret_template.

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

Note : Le JSON doit tre une chane de caractres chappe.

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'hsitez pas forker le projet et ouvrir une Pull Request.

Licence

MIT