Unix pass

██╗   ██╗███╗   ██╗██╗██╗  ██╗    ██████╗  █████╗ ███████╗███████╗    ███╗   ███╗ ██████╗██████╗

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

Connect your existing Unix [`pass`](https://www.passwordstore.org/)/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 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/ / ), 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:

| PASS_MCP_ALLOWED_PATHS | unset (= all) | C