io.github.Neanderthal由 GitHub 账号 Neanderthal 发布v0.2.1更新于 Nov 4, 2026
本地 MCP 访问 Unix pass/GPG，默认只读，支持路径范围和 TOTP。
AI 翻译由 AI 模型根据下方的原文描述翻译，可能有误。
Local MCP access to Unix pass/GPG with read-only defaults, path scopes, and TOTP.
Unix pass 的本地 MCP 服务；无需登录；STDIO；24 个工具。
暂无 AI 概览：以下信息来自注册中心条目和服务本身。
Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。
参照 仓库 中的启动说明。
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.
[Real MCP calls using a synthetic store]
83-second MP4 · How it was recorded
Trying the beta? Report installation feedback. Launch status tracks package and directory publication separately.
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:
pass.See .claude/rules/architecture.md for the full design and security model.
Requires Python 3.11+, uv, pass, GnuPG, and an initialized store.
Install the published PyPI release:
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:
The server can never serve an interactive passphrase prompt itself — pass/gpg will hang. You need one of:
~/.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.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.pass show <name> in a real terminal before talking to the MCP. Cache expires per default-cache-ttl (default 600s).Add to ~/.config/Claude/claude_desktop_config.json (or the platform equivalent):
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.
PASS_MCP_ALLOW_WRITES=1git_status and git_log always; git_pull and git_push need PASS_MCP_ALLOW_NETWORK=1PASS_MCP_ALLOW_DESTRUCTIVE=1Full 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).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.
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.
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.
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.
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.
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.
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.
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:
PASS_MCP_ALLOWED_PATHS and forward it to another tool in the same session.PASS_MCP_ALLOW_WRITES=1, an LLM can overwrite, rename, or generate-over entries in scope.PASS_MCP_ALLOW_DESTRUCTIVE=1, an LLM can re-encrypt your store to a different recipient set, or remove a subfolder's .gpg-id.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:
~/.password-store (and ~/.gnupg) before granting destructive or network access.~/.local/state/unix-pass-mcp/audit.log periodically.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.
来源：README.md，提交 886a632
Inspect the configured password store without decrypting anything. Returns store path, recipient keys per subdirectory (from .gpg-id files), git/agent/signing status, and any configuration warnings. Call this first to confirm the store is reachable and healthy.
无需输入参数。
List all pass-names (entries) in the store, optionally scoped to a subfolder. Returns a flat sorted list of names without the .gpg suffix. Does not decrypt.
subfolderFind pass-names whose leaf name contains `query` (case-insensitive substring). Mirrors `pass find`. Does not decrypt.
query必填subfolderDecrypt and return the password (line 1) for a pass-name. Pass `line` to return a different line (1-indexed). The returned `value` is sensitive. Use it only for the user's explicitly requested task; never quote or repeat it in assistant messages, summaries, logs, or unrelated tool calls. Avoid retrieving it unless necessary. Clients should not log or cache it.
linename必填Decrypt the entry and return one named metadata field (e.g. `URL`, `Username`, `otpauth`). Field lookup is case-insensitive. Returns null `value` if the field is absent. The password line is never returned. Field values may be secrets: use only for the requested task and never quote or repeat them in assistant messages, summaries, logs, or unrelated tool calls.
name必填field必填**Call this whenever any other tool returns `agent_unavailable`** — that error means gpg-agent is up but pinentry can't prompt (typically pinentry-curses + no TTY, the default deadlock when an MCP server is spawned by Claude Desktop/Code). This tool resolves it: pops a desktop password dialog (zenity / kdialog) and decrypts one entry via loopback pinentry. After it succeeds, subsequent `show`/`grep`/etc calls work without TTY-bound pinentry until the agent's cache TTL expires (default 600s, set via `default-cache-ttl` in ~/.gnupg/gpg-agent.conf). Do NOT ask the user to paste their GPG passphrase into chat — the passphrase travels desktop dialog → our process → gpg stdin and the LLM never sees it. Optional `target` is a pass-name to decrypt against (useful when the store has multiple `.gpg-id` recipients and you want to warm a specific key); without it, the smallest in-scope entry is used.
targetDecrypt the entry but return only its shape: which metadata field names exist, whether a password is present, and the raw line count. Useful to inspect entry structure without surfacing the password.
name必填Create or overwrite a single-line entry. The password is passed via stdin (never argv) so it never appears in /proc/<pid>/cmdline. Refuses if the entry exists unless `force=true`. Requires PASS_MCP_ALLOW_WRITES=1.
name必填forcepassword必填Create or overwrite a multi-line entry. Line 1 is the password; subsequent lines should follow `Key: value` convention (URL, Username, otpauth, …). Body is passed via stdin. Refuses if the entry exists unless `force=true`. Requires PASS_MCP_ALLOW_WRITES=1.
body必填name必填forceSet or update one `Key: value` metadata field on an existing entry, preserving the password and all other lines. Field lookup is case-insensitive; existing case is preserved on update, new fields are appended in the requested case. Refuses if the entry does not exist (use `insert_multiline` to create). Pass `simulate=true` to compute the would-be body without writing — useful for agent dry-runs. Requires PASS_MCP_ALLOW_WRITES=1 (also for simulate). Simulated bodies contain the password and other entry data; never quote or repeat them in assistant messages, summaries, logs, or unrelated tool calls.
name必填field必填value必填simulateRemove all lines matching `field` (case-insensitive) from an existing entry, preserving the password and all other lines. No-op if the field is absent. Pass `simulate=true` for a dry-run. Simulated bodies contain secret entry data; never quote or repeat them in assistant messages, summaries, logs, or unrelated tool calls. Requires PASS_MCP_ALLOW_WRITES=1.
name必填field必填simulateGenerate a new password for `name`. `length` defaults to PASSWORD_STORE_GENERATED_LENGTH (or 25). `no_symbols=true` restricts to alphanumerics. `in_place=true` replaces only the first line of an existing entry (preserving metadata) and needs the entry to exist. `force=true` overwrites any existing entry from scratch. Without either flag, refuses if the entry already exists. Returns a sensitive generated password; use only for the requested task and never quote or repeat it in assistant messages, summaries, logs, or unrelated tool calls. Requires PASS_MCP_ALLOW_WRITES=1.
name必填forcelengthin_placeno_symbolsCompute the current TOTP code for an entry containing an `otpauth://` line (pass-otp / browserpass convention). Returns the code plus `seconds_remaining` in the current window — if it's very low (<5s), wait for the next window before submitting. The code is sensitive: use only for the requested task and never quote or repeat it in assistant messages, summaries, logs, or unrelated tool calls.
name必填Return the raw `otpauth://` URI stored on the entry (contains the secret). Use this only when you need to re-enroll the same secret elsewhere; for submitting a code, prefer `otp`. The URI is sensitive: use only for the requested task and never quote or repeat it in assistant messages, summaries, logs, or unrelated tool calls.
name必填Add or replace the `otpauth://` URI on an existing entry, preserving the password and all other lines. The URI is validated before write. Refuses if the entry does not exist (use `insert` first). Requires PASS_MCP_ALLOW_WRITES=1.
uri必填name必填Rename or move an entry/subfolder. Re-encrypts to the destination subfolder's recipients if they differ. Refuses if the destination exists unless `force=true`. Requires PASS_MCP_ALLOW_WRITES=1.
dst必填src必填forceCopy an entry/subfolder. Re-encrypts to the destination subfolder's recipients if they differ. Refuses if the destination exists unless `force=true`. Requires PASS_MCP_ALLOW_WRITES=1.
dst必填src必填forceSearch inside permitted entries for a basic regular expression pattern. **Slow and expensive** — decrypts permitted entries, warming their secret keys in gpg-agent's cache. Caller must pass `confirm_decrypt_all=true` to acknowledge. Returns matched lines (sensitive — they're decrypted content). Never quote or repeat matched content in assistant messages, summaries, logs, or unrelated tool calls. Honours PASS_MCP_GREP_TIMEOUT_SECONDS (default 120s).
pattern必填case_insensitiveconfirm_decrypt_allInspect git state of the password store. Returns whether the working tree is clean, current branch, upstream, ahead/behind counts, and any dirty paths. Refuses if the store is not a git repository (run `pass git init` first).
无需输入参数。
Return recent commits in the password store as `[{hash, subject}, ...]`. `limit` defaults to 20 (max 200). Useful for auditing what changed and when.
limitSync remote commits into the local store via `git pull --ff-only` (no merge commits, no rebase — refuses if local has diverged). Requires PASS_MCP_ALLOW_NETWORK=1 because it reaches out to a remote. Returns `{ok, output, stderr}`. On failure the agent should call `git_status` to diagnose.
无需输入参数。
Push local commits to the configured upstream. Requires PASS_MCP_ALLOW_NETWORK=1. Returns `{ok, output, stderr}`. Does not force-push.
无需输入参数。
Initialize the password store (or a subfolder) with the given GPG recipient(s). Re-encrypts every existing entry in scope to the new recipient set — this is DESTRUCTIVE. Pass an empty `gpg_ids` list to remove the .gpg-id file for the subfolder (entries inherit the parent's recipients). Refuses if the user has no secret key for any of the new recipients (would lock the user out); pass `force=true` to override (e.g. team scenarios where you're delegating access). Requires PASS_MCP_ALLOW_DESTRUCTIVE=1.
forcegpg_ids必填subfolderRe-run `pass init` against the *current* `.gpg-id` recipients (no key change). Use after subkey rotation or to repair a store where some files are encrypted to outdated recipients. Note: `pass init` is a no-op when each file's existing recipients already match the .gpg-id — there is no way to force a fresh ciphertext without changing the recipient set. Requires PASS_MCP_ALLOW_DESTRUCTIVE=1.
subfolder已满足适用检查项的 90%
该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。
请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。
██╗ ██╗███╗ ██╗██╗██╗ ██╗ ██████╗ █████╗ ███████╗███████╗ ███╗ ███╗ ██████╗██████╗██║ ██║████╗ ██║██║╚██╗██╔╝ ██╔══██╗██╔══██╗██╔════╝██╔════╝ ████╗ ████║██╔════╝██╔══██╗██║ ██║██╔██╗ ██║██║ ╚███╔╝ ██████╔╝███████║███████╗███████╗ ██╔████╔██║██║ ██████╔╝██║ ██║██║╚██╗██║██║ ██╔██╗ ██╔═══╝ ██╔══██║╚════██║╚════██║ ██║╚██╔╝██║██║ ██╔═══╝╚██████╔╝██║ ╚████║██║██╔╝ ██╗ ██║ ██║ ██║███████║███████║ ██║ ╚═╝ ██║╚██████╗██║ ╚═════╝ ╚═╝ ╚═══╝╚═╝╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝╚══════╝╚══════╝ ╚═╝ ╚═╝ ╚═════╝╚═╝claude mcp add unix-pass -e 'PASS_MCP_ALLOWED_PATHS=web/*' -- \ uvx --from unix-pass-mcp==0.2.1 unix-pass-mcpPASS_MCP_ALLOW_WRITES=1 \PASS_MCP_ALLOWED_PATHS=web/* \uv run unix-pass-mcp# Arch / Manjarosudo pacman -S pass gnupg pinentry zenity # zenity optional, for unlock_agent
# Debian / Ubuntusudo apt install pass gnupg pinentry-gnome3 zenity
# Fedorasudo dnf install pass gnupg2 pinentry-gnome3 zenity
# macOS (Homebrew)brew install pass gnupg pinentry-macuv sync --locked --extra dev # for developmentuv pip install . # for use{ "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-onlyclaude 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-mcpuv run ruff checkuv run ruff format --checkuv run pytest -q tests/unit # fast testsPASS_MCP_INTEGRATION=1 uv run pytest -q tests/integration # real-GPG tests