MCP Vaultwarden Connector

🔐 MCP Vaultwarden 服务端

一个 MCP（模型上下文协议）服务，为与自托管的 Vaultwarden 实例交互提供简单而可靠的接口。它是官方 Bitwarden 命令行工具（bw）的封装，可让 AI Agent 或自动化脚本以编程方式管理机密信息。

🤔 为什么要做这个项目？

Vaultwarden 是 Bitwarden 的热门轻量级替代方案，但其自动化操作可能较为复杂。官方命令行工具（bw）需要手动管理会话（登录、解锁等），不适合由 AI Agent 使用或在非交互式脚本中使用。

这个 MCP 通过以下方式解决了这一问题：

• 自动管理会话： 按需解锁保险库，并将会话保持在缓存中。
• 提供简单的工具： 通过 MCP 协议提供清晰的函数（get_secret、list_secrets 等）。
• 避免阻塞： 集成超时机制和锁定系统，可靠地处理并发访问。

✨ 功能

• 自动解锁： 首次请求时解锁保险库，并缓存会话密钥。
• 冲突管理： 通过“锁定”机制避免重复并发解锁。
• 完整 API： 支持读取、创建、更新和删除机密信息。
• 机密信息模板： 提供 JSON 模板，方便创建新条目。
• 安全性： 所有加密操作均依赖官方 bw 命令行工具。

---

⚠️ 前提条件

要运行此服务，运行它的机器必须安装 Bitwarden 命令行工具（bw），且该工具必须可通过 PATH 访问。

请按照官方安装说明操作：安装 Bitwarden 命令行工具。

---

📦 安装

方法 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 客户端 ID。
• BW_CLIENTSECRET：您的 API 客户端密钥。
• 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": {}
}

---

🤝 贡献

欢迎贡献！欢迎 fork 此项目并提交 Pull Request。

📝 许可证

MIT