MCP Vaultwarden Connector

🔐 MCP Vaultwarden サーバー

セルフホスト可能な Vaultwarden インスタンスとやり取りするための、シンプルで堅牢なインターフェースを提供する MCP（Model-Context-Protocol）サーバーです。Bitwarden の公式 CLI（bw）をラップし、AI エージェントや自動化スクリプトがプログラムからシークレットを管理できるようにします。

🤔 このプロジェクトの目的

Vaultwarden は Bitwarden の人気のある軽量な代替手段ですが、自動化は複雑になることがあります。公式 CLI（bw）ではセッション（ログイン、ロック解除など）を手動で管理する必要があり、AI エージェントや非対話型スクリプトでの利用には適していません。

この MCP は、次の方法でこの問題を解決します。

• セッションを自動管理： 要求に応じて保管庫のロックを解除し、セッションをキャッシュして有効な状態に保ちます。
• シンプルなツールを提供： MCP プロトコル経由で明確な関数（get_secret、list_secrets など）を提供します。
• 処理の停止を防止： タイムアウトとロック機構を組み込み、並行アクセスを確実に管理します。

✨ 機能

• 自動ロック解除： 最初の要求時に保管庫のロックを解除し、セッションキーをキャッシュします。
• 競合管理： 「ロック」機構により、複数のロック解除処理が同時に実行されるのを防ぎます。
• 包括的な API： シークレットの読み取り、作成、更新、削除をサポートします。
• シークレットテンプレート： 新しい項目を簡単に作成できる JSON テンプレートを提供します。
• セキュリティ： すべての暗号化処理に公式 CLI bw を使用します。

---

⚠️ 前提条件

このサーバーを実行するには、実行するマシンに Bitwarden CLI（bw）がインストールされ、PATH からアクセスできる必要があります。

公式のインストール手順に従ってください：Bitwarden CLI のインストール。

---

📦 インストール

方法 1：NPM 経由（推奨）

gemini-cli などの MCP クライアントで利用する場合、これが最も簡単な方法です。

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"
      }
    }
  }
}

方法 2：ソースからインストール（Git）

1. リポジトリをクローンします：

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

2. 依存関係をインストールします：

   npm install
   

3. 設定して起動します： .env.example をもとに .env ファイルを作成して内容を記入し、サーバーを起動します。

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

---

🔒 設定とセキュリティ

環境変数を使用して設定します。

• BITWARDEN_HOST：Vaultwarden インスタンスの URL。
• BW_CLIENTID：API の Client ID。
• BW_CLIENTSECRET：API の Client Secret。
• BW_MASTER_PASSWORD：マスターパスワード。

セキュリティに関する警告： BW_MASTER_PASSWORD の管理は非常に重要です。

• .env ファイルやシークレットを Git リポジトリに絶対にコミットしないでください。
• 本番環境では、オーケストレーターのシークレット（Kubernetes Secrets、Docker Secrets）や専用サービス（HashiCorp Vault）など、より堅牢なシークレット管理方法を使用してください。
• この MCP は、管理された安全な環境で実行することを想定しています。

---

🧰 ツールリファレンス（API）

この MCP が提供するツールと呼び出し例を紹介します。

get_secret

名前または ID でシークレットを取得します。

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

list_secrets

指定した語句を含むシークレットを検索します。

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

get_secret_template

新しいシークレットを作成するための JSON テンプレートを取得します。

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

有効なタイプ：login、note、card、identity。

create_secret

新しいアイテムを作成します。まず 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\\\"}]}}"
  }
}

注：JSON はエスケープされた文字列にする必要があります。

update_secret

ID を指定して既存のシークレットを更新します。

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

delete_secret

ID を指定してシークレットを削除します。

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

sync

ローカルの保管庫とリモートサーバーの同期を強制します。

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

---

🤝 貢献

貢献を歓迎します！お気軽にプロジェクトをフォークして、Pull Request を作成してください。

📝 ライセンス

MIT