Unix pass

██╗   ██╗███╗   ██╗██╗██╗  ██╗    ██████╗  █████╗ ███████╗███████╗    ███╗   ███╗ ██████╗██████╗
██║   ██║████╗  ██║██║╚██╗██╔╝    ██╔══██╗██╔══██╗██╔════╝██╔════╝    ████╗ ████║██╔════╝██╔══██╗
██║   ██║██╔██╗ ██║██║ ╚███╔╝     ██████╔╝███████║███████╗███████╗    ██╔████╔██║██║     ██████╔╝
██║   ██║██║╚██╗██║██║ ██╔██╗     ██╔═══╝ ██╔══██║╚════██║╚════██║    ██║╚██╔╝██║██║     ██╔═══╝
╚██████╔╝██║ ╚████║██║██╔╝ ██╗    ██║     ██║  ██║███████║███████║    ██║ ╚═╝ ██║╚██████╗██║
 ╚═════╝ ╚═╝  ╚═══╝╚═╝╚═╝  ╚═╝    ╚═╝     ╚═╝  ╚═╝╚══════╝╚══════╝    ╚═╝     ╚═╝ ╚═════╝╚═╝

状态 — M5 已完成。 读取 · 安全写入 · 密钥管理 · TOTP/OTP · git · 加固功能均已发布。 24 个工具，配备单元测试、真实 GPG 集成测试和 stdio 协议回归测试套件。 请参阅安装示例、演示和 发布/发布流程说明。

演示

83 秒 MP4 · 录制方式

正在试用 Beta 版？反馈安装体验。 发布状态分别跟踪软件包和目录的发布进度。

目录

• 为何创建此项目
• 快速入门
• 要求
• 安装
• 接入 MCP 主机
• 工具
• 配置
• 安全态势
• 开发
• 免责声明
• 许可证

为何创建此项目

pass 是对 gpg(1) 和文件系统的轻量封装。任何可以调用 Shell 的程序都能使用它——但直接将它暴露给 LLM，无异于自找 rm -rf 的麻烦。本服务提供：

• 在安全的 pass 子集之上构建的类型化 MCP 接口。
• 默认只读；写入和破坏性操作均需通过明确的环境变量选择启用。
• 严格验证输入——不使用 Shell、不允许路径逃逸、不允许通过 stdin 偷带机密。
• 经过净化的错误输出、仅追加的审计日志，以及 gpg-agent 预检。

完整设计和安全模型请参阅 .claude/rules/architecture.md。

快速入门

需要 Python 3.11+、uv、pass、GnuPG 和已初始化的存储。 安装已发布到 PyPI 的版本：

claude mcp add unix-pass -e 'PASS_MCP_ALLOWED_PATHS=web/*' -- \
  uvx --from unix-pass-mcp==0.2.1 unix-pass-mcp

可直接复制粘贴的配置：Codex、 Claude Code、 Claude Desktop。 源码检出开发和其他客户端设置详情，请参阅安装说明。

这样即可使用只读接口。要启用修改操作：

PASS_MCP_ALLOW_WRITES=1 \
PASS_MCP_ALLOWED_PATHS=web/* \
uv run unix-pass-mcp

要求

必需

Pinentry — 选择一种方式

服务本身无法弹出交互式密码短语提示框——pass/gpg 会一直挂起。你需要使用以下一种方式：

1. 在 ~/.gnupg/gpg-agent.conf 中配置一个 GUI pinentry——pinentry-gnome3、pinentry-qt、pinentry-qt5 或 pinentry-gtk-2。每个缓存窗口内首次解密时，桌面会弹出对话框。推荐。
2. 安装 zenity 或 kdialog——每个缓存窗口调用一次 unlock_agent MCP 工具，为 gpg-agent 预热缓存。如果你无法修改 gpg-agent.conf，请使用此方式。
3. 使用已预热的 Agent——在与 MCP 通信前，先在真实终端中运行 pass show <name>。缓存会在 default-cache-ttl 设定的时间后过期（默认 600s）。

OS 安装提示

# Arch / Manjaro
sudo pacman -S pass gnupg pinentry zenity         # zenity optional, for unlock_agent

# Debian / Ubuntu
sudo apt install pass gnupg pinentry-gnome3 zenity

# Fedora
sudo dnf install pass gnupg2 pinentry-gnome3 zenity

# macOS (Homebrew)
brew install pass gnupg pinentry-mac

可选组件

开发

安装

uv sync --locked --extra dev # for development
uv pip install .             # for use

接入 MCP 主机

Claude Desktop

添加到 ~/.config/Claude/claude_desktop_config.json（或对应平台的配置文件）：

{
  "mcpServers": {
    "pass": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/unix-pass-mcp", "unix-pass-mcp"],
      "env": {
        "PASSWORD_STORE_DIR": "/home/you/.password-store"
      }
    }
  }
}

Claude Code

# Read-only
claude mcp add pass -- uv run --directory /absolute/path/to/unix-pass-mcp unix-pass-mcp

# With writes enabled and path scope (recommended pairing)
claude mcp add pass -s user \
  -e PASS_MCP_ALLOW_WRITES=1 \
  -e PASS_MCP_ALLOWED_PATHS='web/*' \
  -- uv run --directory /absolute/path/to/unix-pass-mcp unix-pass-mcp

每个 -e KEY=VALUE 标志都会为启动的服务设置一个环境变量。若要更改现有服务的环境变量，请先运行 claude mcp remove pass -s user，然后重新添加——CLI 不支持就地编辑。使用 claude mcp get pass 验证。

驱动自主 Agent

对于将 unix-pass-mcp 与可控制浏览器的 MCP 结合使用的账号创建 / 资料填写工作流，请将 .claude/rules/agent-workflow.md 加载到 Agent 的系统提示词中。该文件定义了规范的命名约定（web/<domain>/<handle>）、正文格式，以及注册 / 登录 / 轮换流程。

工具

共 24 个工具，按能力门控分组。

只读——始终可用

写入 — 需设置 PASS_MCP_ALLOW_WRITES=1 才能使用

Git — git_status 和 git_log 始终可用；git_pull 和 git_push 需设置 PASS_MCP_ALLOW_NETWORK=1

破坏性操作 — 需设置 PASS_MCP_ALLOW_DESTRUCTIVE=1 才能使用

完整的机器可读接口——包括每个参数和每个错误代码——位于 .claude/rules/api.md。

配置

服务器专用环境变量：

标准 pass 环境变量会传递过去（PASSWORD_STORE_DIR、PASSWORD_STORE_KEY、PASSWORD_STORE_UMASK 等）。完整列表请参阅 .claude/rules/architecture.md §5。

不会传递的变量：

• PASSWORD_STORE_GPG_OPTS — 恶意环境可借此注入 gpg 标志，例如 --recipient（悄无声息地将数据重新加密给攻击者）或 --output（外泄解密内容）。
• PASSWORD_STORE_X_SELECTION、PASSWORD_STORE_CLIP_TIME — 剪贴板工具已移除（通过 MCP 使用时没有意义）。

安全态势

服务指示模型将返回的机密视为机密信息，绝不在回复、摘要、日志或无关的工具调用中复述。这只是对模型的指导，并非技术层面的日志隔离措施：MCP 客户端仍可能将原始工具结果保存在对话记录中。请相应地检查并配置主机的对话记录和日志策略。

将机密传递给本地应用程序

此服务尚未提供从 pass 到本地应用程序的隐藏式服务端传递机制。show 工具会将请求的值返回给 MCP 主机和模型。请勿让 Agent 通过 shell 运行 pass show 作为变通方案：这样会绕过此服务的路径检查和审计策略，并可能导致输出暴露在工具历史记录中。通用传递机制需要借助本地客户端／代理路径，确保机密不会进入助手对话记录，或通过明确由用户介入的方式传递。仅靠 MCP 工具说明无法提供此类通道。

运行行为

限定范围的搜索

grep 会先筛选允许访问的条目名称，再逐个解密，并使用基本正则表达式搜索条目正文。类似标头的内容不会更改条目名称。模式会作为操作数处理，包括以 - 开头的模式；无效模式会在解密前导致操作失败。PASS_MCP_GREP_TIMEOUT_SECONDS 是适用于整个搜索过程的正数有限总时限。redacted_entries 始终为零，因为被排除的条目不会参与搜索。

文件系统隔离

条目访问会拒绝符号链接文件和目录组件，包括密码库内部的链接。发现条目和自动解锁的目标选择过程会跳过链接。显式指定的解锁目标会在探测 Agent 前进行验证。请确保本地密码库归可信用户所有：这些 CLI 检查无法隔离同一用户运行的其他进程对文件系统进行的并发更改。

发现与 git 范围

list 和 find 会排除不允许访问的条目。启用路径范围限制时，接收者发现功能只会报告可见条目的祖先目录。远程 URL 会省略用户信息、查询参数和片段。Git 工具会操作整个代码库，因此要求访问不受限（未设置路径允许列表，或明确授予 *）；部分路径授权不足以授权访问 git 历史记录或执行代码库范围的网络操作。

结构化元数据和敏感结果

show_metadata 会返回 field_names、password_present 和 raw_lines。它不会 返回字段值、密码、自由文本或 OTP URI。此行为取代了原先的 fields 映射。若要显式读取敏感字段，请使用 show_field。 这两个字段编辑工具都会声明输出敏感，因为模拟结果包含完整的解密前后正文。自定义敏感元数据只是主机提示，并非协议对日志记录或缓存的保证。搜索查询不会被审计。

PASS_MCP_TIMEOUT_SECONDS 用于设置默认子进程超时时间。它必须是正的有限数值；无效值会在命令执行前导致失败。显式操作预算（搜索、密钥管理和网络操作）会覆盖此值。

运行时和取消

MCP 处理程序在工作线程中运行，因此缓慢的 GPG 操作不会阻塞协议处理。变更类工具调用会串行执行，以防止读/修改/写入操作重叠。取消会向工作线程发送信号并终止其子进程组；每条命令的超时时间仍会限制执行时长。取消无法回滚 pass 已完成的更改；重试写入前请检查条目。生产环境中的子进程启动（包括解锁对话框）都集中在 pass_cli.execute 中。本地工具声明 openWorldHint: false；网络 git 工具声明 openWorldHint: true。

MCP SDK 兼容性

服务器使用官方 SDK v2 的 MCPServer API，并要求 mcp>=2.3,<3。 其 stdio 传输同时支持旧版初始化和 2026 年 7 月推出的按请求元数据/发现机制。 测试会以两种模式启动真实的 stdio 客户端。锁文件记录了经过测试的依赖集；使用 uv sync --locked --extra dev 可复现该环境。

开发

uv run ruff check
uv run ruff format --check
uv run pytest -q tests/unit                                 # fast tests
PASS_MCP_INTEGRATION=1 uv run pytest -q tests/integration   # real-GPG tests

集成测试套件会在临时 GNUPGHOME 中创建一个仅供测试使用的 RSA 密钥（有效期 1 天，无密码），并运行真实的 pass 进行测试。CI 会在 Python 3.11 / 3.12 / 3.13 上运行这两个层级的测试。

免责声明

unix-pass-mcp 是密码库与非确定性大模型之间的桥梁；在大多数实际部署中，它还连接着密码库与所有共享同一模型会话的其他 MCP 服务（浏览器自动化、Shell 执行、Web 请求）。即使默认禁用了所有权限门控，安装此服务的目的就是让大模型访问你的机密。以下情况并非错误：

• 大模型可以被提示（由你、浏览器 MCP 加载的恶意网页，或遭到投毒的工具结果提示），解密 PASS_MCP_ALLOWED_PATHS 范围内的任意条目，并将其转发给同一会话中的其他工具。
• 设置 PASS_MCP_ALLOW_WRITES=1 后，大模型可以覆盖、重命名或生成条目，取代范围内的现有条目。
• 设置 PASS_MCP_ALLOW_DESTRUCTIVE=1 后，大模型可以将你的密码库重新加密给另一组接收者，或删除某个子文件夹的 .gpg-id。
• 设置 PASS_MCP_ALLOW_NETWORK=1 后，大模型可以向配置的 git 远程仓库推送提交，包括凭据变更。

权限门控、路径允许列表、审计日志、敏感输出标记和验证加固措施，可以缩小错误和提示注入的影响范围。但它们并不能让无人监督的 Agent 安全地访问生产凭据库。请将上述安全态势视为针对恶意且快速演变的威胁模型所做的尽力而为的工程实践，而非正式保证。

你须全权负责：

• 启用哪些权限门控，以及在哪些密码库上启用。
• 运行此服务的 MCP 主机的信任边界——它会记录、缓存、发送到遥测系统什么内容，或允许其他服务查看什么内容。
• 在授予破坏性操作或网络访问权限前，备份 ~/.password-store（以及 ~/.gnupg）。
• 定期检查 ~/.local/state/unix-pass-mcp/audit.log。
• 从 Agent 造成的任何错误中恢复——没有撤销操作。

本软件按“原样”提供，不附带任何明示或默示的保证，包括但不限于适销性、特定用途适用性和不侵权保证。作者和贡献者不对任何索赔、损害或其他责任承担责任，包括但不限于数据丢失、凭据泄露、密码库锁定、机密意外披露或服务中断，无论这些后果是由错误、提示注入、配置错误，还是任何其他对本软件的使用或滥用造成。完整的 MIT 条款请参阅 LICENSE。

本项目与 Anthropic、pass(1) 的维护者（Jason A. Donenfeld 和贡献者）、GnuPG 项目或任何 MCP 主机供应商均无关联，也未获得其认可或赞助。所有商标均归其各自所有者所有。

许可证

MIT——请参阅 LICENSE。