veracrypt-mcp

veracrypt-mcp

用于挂载和卸载 VeraCrypt 容器的 MCP（模型上下文协议）服务，优先保障密码处理安全。

容器挂载后，MCP 客户端（例如 Claude Code）即可使用常规文件工具读取和编辑其中的文件。只需说“挂载我的保险库”，处理文件，然后说“卸载我的保险库”。

mcp-name: io.github.bitterdev/veracrypt-mcp

功能

• mount_container：挂载 VeraCrypt 容器（可选挂载点、PIM、只读模式、密钥文件）
• unmount_container：按容器路径或挂载点卸载
• list_mounted_containers：显示所有已挂载的 VeraCrypt 卷
• 默认保险库：通过环境变量配置一次容器后，无需任何参数即可“挂载我的保险库”

安全模型

卷密码绝不会作为命令行参数传递。命令行参数对机器上的每个进程都可见（ps aux），因此此服务始终使用 VeraCrypt 官方的 --stdin 选项，通过标准输入将密码传递给 VeraCrypt。

密码有两种来源：

1. OS 钥匙串（推荐）

将密码存入 OS 钥匙串一次。MCP 工具随后只会接收钥匙串账户名，因此密码不会进入大模型上下文、聊天记录或对话转录。

macOS（Keychain）：

security add-generic-password -s veracrypt-mcp -a my-container -w
# you will be prompted for the password interactively

Linux（libsecret / GNOME Keyring，需要 libsecret-tools）：

secret-tool store --label="veracrypt-mcp my-container" service veracrypt-mcp account my-container

然后使用 keychain_account: "my-container" 挂载。

2. 直接提供密码（备用方式）

你可以直接向工具传递 password。密码仍会通过标准输入传递给 VeraCrypt（不会出现在进程列表中），但会经过大模型对话，并可能存储在聊天记录中。请尽可能使用钥匙串来源。

3. 密钥文件和硬件令牌

keyfiles（或以逗号分隔的 VERACRYPT_MCP_KEYFILES）会映射到 VeraCrypt 的 -k，并可与空密码配合使用。如果密钥文件缺失，工具会返回 Key nicht freigegeben，而不会尝试其他凭据。若已配置默认密钥文件并设置钥匙串账户，缺失的密钥文件会回退到钥匙串密码一次（适用于卷仍使用旧密码的情况）；如果 VeraCrypt 拒绝该密码，则会再次返回 Key nicht freigegeben。

对于仅在用户解锁硬件令牌（YubiKey 加 PIN）后才可用的密钥文件，请设置 VERACRYPT_MCP_UNLOCK_COMMAND。未传递凭据时，工具会使用 --interaktiv 运行该命令；该命令会提示用户，挂载卷，并在未释放密钥时以非零状态退出。不会缓存任何内容，因此每次挂载都需要用户输入。

其他说明：

• 密码绝不会被记录，也不会包含在工具结果或错误消息中。
• Python 无法安全地清除内存中的字符串；如需最高安全性，请使用钥匙串来源并为容器设置专用密码。

要求

• Python >= 3.10
• VeraCrypt，且命令行二进制文件可用（veracrypt 位于 PATH、macOS 应用程序包中，或设置 VERACRYPT_PATH）
• macOS：macFUSE（VeraCrypt 挂载所需）
• Linux 钥匙串来源：libsecret-tools（secret-tool）

安装

pip install git+https://github.com/bitterdev/veracrypt-mcp.git

也可以从本地克隆安装：

git clone https://github.com/bitterdev/veracrypt-mcp.git
cd veracrypt-mcp
pip install .

配置

Claude Code

claude mcp add veracrypt -- veracrypt-mcp

使用默认保险库（推荐）：

claude mcp add veracrypt \
  -e VERACRYPT_MCP_CONTAINER="/path/to/vault.hc" \
  -e VERACRYPT_MCP_KEYCHAIN_ACCOUNT="my-vault" \
  -- veracrypt-mcp

Claude Desktop / 通用 MCP 客户端

{
  "mcpServers": {
    "veracrypt": {
      "command": "veracrypt-mcp",
      "env": {
        "VERACRYPT_MCP_CONTAINER": "/path/to/vault.hc",
        "VERACRYPT_MCP_KEYCHAIN_ACCOUNT": "my-vault"
      }
    }
  }
}

此服务通过标准输入/输出运行。

使用示例

配置了默认保险库时：

挂载我的保险库

卸载我的保险库

显式指定，不使用默认值：

使用钥匙串账户 "my-container" 挂载容器 /Users/me/secret.hc

在指定挂载点以只读模式挂载：

将 /Users/me/secret.hc 以只读模式挂载到 ~/mnt/secret，钥匙串账户为 "my-container"

环境变量

变量	说明
VERACRYPT_MCP_CONTAINER	未提供 container_path 时使用的默认容器路径
VERACRYPT_MCP_KEYCHAIN_ACCOUNT	未提供密码来源时使用的默认密钥环账户
VERACRYPT_MCP_MOUNT_POINT	默认挂载目录（否则由 VeraCrypt 自动选择）
VERACRYPT_MCP_KEYFILES	默认密钥文件路径，以逗号或换行符分隔
VERACRYPT_MCP_UNLOCK_COMMAND	交互式解锁命令，调用时附带 --interaktiv
VERACRYPT_PATH	VeraCrypt 二进制文件不在 PATH 中时，指定其绝对路径

测试

python -m unittest discover -s tests

测试会创建临时容器，并需要 VeraCrypt CLI。

许可证

MIT，详见 LICENSE。

作者

Fabian Bitter ([email protected])