MCP Vaultwarden Connector

Fornece uma ponte para scripts e agentes de IA interagirem com uma instância auto-hospedada do Vaultwarden.

Documentação

🔐 MCP Vaultwarden Server

Um servidor MCP (Model-Context-Protocol) que expõe uma interface simples e robusta para interagir com uma instância Vaultwarden auto-hospedada. Ele atua como um wrapper em torno da CLI oficial do Bitwarden (bw), permitindo que agentes de IA ou scripts de automação gerenciem segredos de forma programática.

🤔 Por que este projeto?

Vaultwarden é uma alternativa popular e leve ao Bitwarden, mas sua automação pode ser complexa. A CLI oficial (bw) requer gerenciamento manual da sessão (login, unlock, etc.), o que não é ideal para uso por agentes de IA ou em scripts não interativos.

Este MCP resolve esse problema ao:

Gerenciando automaticamente a sessão: Ele desbloqueia o cofre sob demanda e mantém a sessão ativa em cache.
Expondo ferramentas simples: Fornece funções claras (get_secret, list_secrets, etc.) via o protocolo MCP.
Prevenindo bloqueios: Integra timeouts e um sistema de bloqueio para gerenciar acessos concorrentes de forma confiável.

✨ Funcionalidades

Auto-desbloqueio: O cofre é desbloqueado na primeira solicitação e a chave de sessão é armazenada em cache.
Gerenciamento de Conflitos: Um mecanismo de "lock" impede desbloqueios múltiplos e concorrentes.
API Completa: Suporta leitura, criação, atualização e exclusão de segredos.
Modelos de Segredos: Fornece templates JSON para criar novos itens facilmente.
Segurança: Baseia-se na CLI bw oficial para todas as operações criptográficas.

⚠️ Pré-requisitos

Para que este servidor funcione, a máquina que o executa deve ter a CLI Bitwarden (bw) instalada e acessível no PATH.

Siga as instruções oficiais de instalação: Instalar a CLI Bitwarden.

📦 Instalação

Método 1: Via NPM (Recomendado)

É o método mais simples para uso com um cliente MCP como gemini-cli.

Configure seu cliente para iniciar o servidor 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étodo 2: A partir das Fontes (Git)

Clone o repositório:

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

Instale as dependências:
```
npm install
```
Configure e execute: Crie um arquivo .env a partir de .env.example e preencha-o, depois execute o servidor.
```
cp .env.example .env
nano .env
node server.js
```

🔒 Configuração e Segurança

A configuração é feita por meio de variáveis de ambiente.

BITWARDEN_HOST: A URL da sua instância Vaultwarden.
BW_CLIENTID: Seu Client ID de API.
BW_CLIENTSECRET: Seu Client Secret de API.
BW_MASTER_PASSWORD: Sua senha principal.

AVISO DE SEGURANÇA: O gerenciamento do BW_MASTER_PASSWORD é crítico.

Nunca commitar seu arquivo .env ou seus segredos em um repositório Git.
Para uso em produção, prefira métodos de gerenciamento de segredos mais robustos, como os segredos do seu orquestrador (Kubernetes Secrets, Docker Secrets) ou um serviço dedicado (HashiCorp Vault).
Este MCP é projetado para ser executado em um ambiente controlado e seguro.

🧰 Referência das Ferramentas (API)

Aqui estão as ferramentas expostas por este MCP, com exemplos de chamadas.

`get_secret`

Recupera um segredo pelo nome ou ID.

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

`list_secrets`

Pesquisa segredos que contenham um termo.

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

`get_secret_template`

Obtém um modelo JSON para criar um novo segredo.

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

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

`create_secret`

Cria um novo item. Use primeiro 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: O JSON deve ser uma string de caracteres escapada.

`update_secret`

Atualiza um segredo existente pelo ID.

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

`delete_secret`

Exclui um segredo pelo ID.

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

`sync`

Força a sincronização do cofre local com o servidor remoto.

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

🤝 Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para fazer um fork do projeto e abrir uma Pull Request.

📝 Licença

MIT