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

Status — M5 complete. Read · safe-write · key administration · TOTP/OTP · git · hardening surfaces all shipped. 24 tools, 346 unit tests + 45 real-GPG integration tests, all green. Distribution (M6) is next on the roadmap.

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

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.

# 1. Install
uv pip install .

# 2. Run (speaks MCP over stdio)
uv run unix-pass-mcp

# 3. Wire into Claude Code
claude mcp add pass -- uv run --directory /absolute/path/to/unix-pass-mcp unix-pass-mcp

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

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).

# 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 --extra dev          # for development
uv pip install .             # for use

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

# 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.

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.

24 tools, grouped by capability gate.

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

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).

uv run ruff check
uv run ruff format --check
uv run pytest -q tests/unit                                 # 346 fast tests
PASS_MCP_INTEGRATION=1 uv run pytest -q tests/integration   # 45 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.

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.

MIT — see LICENSE.