Unix pass

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

Connect your existing Unix pass/GPG store to AI tools.

Read-only by default. Writes, key administration, and network ops behind explicit env opt-ins. Single-chokepoint subprocess. Strict input validation. No shell, no clipboard, no secrets in logs.

Status — M5 complete. Read · safe-write · key administration · TOTP/OTP · git · hardening surfaces all shipped. 24 tools with unit, real-GPG integration, and stdio protocol regression suites. See installation examples, the demo, and release/publishing instructions.

Demo

83-second MP4 · How it was recorded

Trying the beta? Report installation feedback. Launch status tracks package and directory publication separately.

Table of contents

• Why this exists
• Quickstart
• Requirements
• Install
• Wire into an MCP host
• Tools
• Configuration
• Security posture
• Development
• Disclaimer
• License

Why this exists

pass is a thin wrapper around gpg(1) and the filesystem. Anything that can shell out can use it — but exposing it raw to an LLM is a recipe for rm -rf regret. This server provides:

• A typed MCP surface over the safe subset of pass.
• Read-only by default; writes and destructive ops behind explicit env opt-ins.
• Strict input validation — no shell, no path escapes, no stdin smuggling of secrets.
• Sanitized error output, append-only audit log, and gpg-agent preflight.

See .claude/rules/architecture.md for the full design and security model.

Quickstart

Requires Python 3.11+, uv, pass, GnuPG, and an initialized store. Install the published PyPI release:

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

Copy-paste configurations: Codex, Claude Code, Claude Desktop. For source-checkout development and other client setup details, see installation.

That gets you the read-only surface. To enable mutations:

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

Requirements

Required

Pinentry — pick one

The server can never serve an interactive passphrase prompt itself — pass/gpg will hang. You need one of:

1. A GUI pinentry configured in ~/.gnupg/gpg-agent.conf — pinentry-gnome3, pinentry-qt, pinentry-qt5, or pinentry-gtk-2. The first decrypt of each cache window pops a desktop dialog. Recommended.
2. zenity or kdialog installed — call the unlock_agent MCP tool once per cache window to warm gpg-agent. Use this if you can't change gpg-agent.conf.
3. A pre-warmed agent — run pass show <name> in a real terminal before talking to the MCP. Cache expires per default-cache-ttl (default 600s).

OS install hints

# 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

Optional

Development

Install

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

Wire into an MCP host

Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json (or the platform equivalent):

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

Each -e KEY=VALUE flag sets one env var on the spawned server. To change env on an existing server, claude mcp remove pass -s user then re-add — the CLI has no in-place edit. Verify with claude mcp get pass.

Driving an autonomous agent

For account creation / profile filling workflows that combine unix-pass-mcp with a browser-controlling MCP, load .claude/rules/agent-workflow.md into the agent's system prompt. It defines the canonical naming convention (web/<domain>/<handle>), body format, and signup/login/rotation loops.

Tools

24 tools, grouped by capability gate.

Read-only — always available

Writes — gated behind PASS_MCP_ALLOW_WRITES=1

Git — git_status and git_log always; git_pull and git_push need PASS_MCP_ALLOW_NETWORK=1

Destructive — gated behind PASS_MCP_ALLOW_DESTRUCTIVE=1

Full machine-readable surface — every arg, every error code — lives in .claude/rules/api.md.

Configuration

Server-specific env vars:

Standard pass env vars are passed through (PASSWORD_STORE_DIR, PASSWORD_STORE_KEY, PASSWORD_STORE_UMASK, …). See .claude/rules/architecture.md §5 for the full list.

Not propagated:

• PASSWORD_STORE_GPG_OPTS — lets a hostile env inject gpg flags like --recipient (silent re-encryption to attacker) or --output (decryption exfiltration).
• PASSWORD_STORE_X_SELECTION, PASSWORD_STORE_CLIP_TIME — clipboard tools dropped (meaningless over MCP).

Security posture

The server instructions tell the model to treat returned secrets as confidential and never repeat them in responses, summaries, logs, or unrelated tool calls. This is guidance for the model, not a technical logging boundary: an MCP client may still store raw tool results in its conversation transcript. Review and configure the host's transcript and logging policy accordingly.

Operational behavior

Scoped search

grep selects allowed entry names before decryption, decrypts each separately, and searches its body with a basic regular expression. Header-like content never changes the entry name. Patterns are operands, including those starting with -; invalid patterns fail before decryption. PASS_MCP_GREP_TIMEOUT_SECONDS is a positive, finite total budget for the entire search. redacted_entries remains zero because excluded entries are never searched.

Filesystem containment

Entry access rejects symlinked files and directory components, including links within the store. Discovery and automatic unlock target selection skip links. Explicit unlock targets are validated before agent probes. Keep the local store under trusted ownership: these CLI checks do not sandbox concurrent filesystem changes by another process running as the same user.

Discovery and git scope

list and find omit excluded entries. Recipient discovery reports only ancestors of visible entries when path scoping is active. Remote URLs omit userinfo, query parameters, and fragments. Git tools operate on the whole repository and require unrestricted access (no path allowlist, or an explicit * grant); partial path grants cannot authorize git history or repository-wide network operations.

Structural metadata and sensitive results

show_metadata returns field_names, password_present, and raw_lines. It never returns field values, passwords, free text, or OTP URIs. This replaces the former fields mapping. Use show_field for an explicitly sensitive field read. Both field-edit tools advertise sensitive output because simulations include the complete decrypted before/after bodies. Custom sensitive metadata is a host hint, not a protocol guarantee against logging or caching. Search queries are not audited.

PASS_MCP_TIMEOUT_SECONDS sets the default subprocess timeout. It must be a positive finite number; invalid values fail before command execution. Explicit operation budgets (search, key administration, and network operations) override it.

Runtime and cancellation

MCP handlers run in worker threads so slow GPG operations do not block protocol processing. Mutating tool calls are serialized to prevent overlapping read/modify/write operations. Cancellation signals the worker and terminates its subprocess group; per-command timeouts still bound execution. Cancellation cannot roll back changes already completed by pass; inspect the entry before retrying a write. Production subprocess launches, including unlock dialogs, are centralized in pass_cli.execute. Local tools advertise openWorldHint: false; network git tools advertise openWorldHint: true.

MCP SDK compatibility

The server uses the official SDK v2 MCPServer API and requires mcp>=2.3,<3. Its stdio transport supports both legacy initialization and July 2026 per-request metadata/discovery. Tests launch real stdio clients in both modes. The lockfile records the tested dependency set; use uv sync --locked --extra dev to reproduce it.

Development

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

The integration suite mints a throwaway RSA key in an ephemeral GNUPGHOME (1-day expiry, no passphrase) and exercises real pass. CI runs both tiers across Python 3.11 / 3.12 / 3.13.

Disclaimer

unix-pass-mcp is a bridge between your password store and a non-deterministic large language model — and, in most realistic deployments, between your password store and every other MCP server that shares the same model session (browser automation, shell execution, web requests). Even with every gate disabled by default, the purpose of installing this server is to grant an LLM access to your secrets. The following are not bugs:

• An LLM can be prompted (by you, by a hostile webpage your browser MCP loads, by a poisoned tool result) to decrypt any entry within PASS_MCP_ALLOWED_PATHS and forward it to another tool in the same session.
• With PASS_MCP_ALLOW_WRITES=1, an LLM can overwrite, rename, or generate-over entries in scope.
• With PASS_MCP_ALLOW_DESTRUCTIVE=1, an LLM can re-encrypt your store to a different recipient set, or remove a subfolder's .gpg-id.
• With PASS_MCP_ALLOW_NETWORK=1, an LLM can push commits — including credential changes — to your configured git remote.

The capability gates, path allowlist, audit log, sensitive-output flags, and validation hardening reduce the blast radius of mistakes and prompt injection. They do not make it safe to point an unsupervised agent at a production credential store. Treat the security posture documented above as best-effort engineering against a hostile and rapidly-evolving threat model, not a formal guarantee.

You are solely responsible for:

• Which capability gates you enable, and on which stores.
• The trust boundary of the MCP host you run this against — what it logs, caches, ships to telemetry, or lets other servers see.
• Backing up ~/.password-store (and ~/.gnupg) before granting destructive or network access.
• Reviewing ~/.local/state/unix-pass-mcp/audit.log periodically.
• Recovering from any mistake an agent makes — there is no undo.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. THE AUTHORS AND CONTRIBUTORS SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY — INCLUDING BUT NOT LIMITED TO DATA LOSS, CREDENTIAL COMPROMISE, STORE LOCK-OUT, UNINTENDED DISCLOSURE OF SECRETS, OR LOSS OF SERVICE — WHETHER ARISING FROM BUGS, PROMPT INJECTION, MISCONFIGURATION, OR ANY OTHER USE OR MISUSE OF THE SOFTWARE. See the LICENSE for the full MIT terms.

This project is not affiliated with, endorsed by, or sponsored by Anthropic, the maintainers of pass(1) (Jason A. Donenfeld and contributors), the GnuPG project, or any MCP host vendor. All trademarks are the property of their respective owners.

License

MIT — see LICENSE.