Keystash MCP server

keystash 🔑

值留给钥匙串，AI 只拿引用名。

The Keychain keeps the values; your AI agent only ever gets references.

keystash 让 AI 助手（MCP、Claude Code、任何 agent）帮你管理 API key、token、密码， 而不让它看见它们。

v0.4.0 起：值存在 macOS 登录钥匙串，磁盘上只剩元数据，而且全库没有 read 工具 —— 没有任何一个接口会把密钥交给 AI。

一句话：这一版的安全性来自「没有 read 工具」＋「全库没有明文出口」，不是来自「用了什么加密」。

English

Why keystash

The usual advice — "don't paste your API key into the chat" — stopped working the day agents became useful. An agent that cannot read OPENAIAPIKEY cannot rotate it, cannot call the API on your behalf, cannot tell you which key expires next month.

So the goal is not "the agent never touches keys". It is the agent manages keys it cannot see:

never printed, never returned by any API.

• The value goes into the macOS login Keychain. It is never written to a file this tool owns,

Metadata is deliberately not secret — so listing and editing it needs no unlock.

• Only metadata (name, tags, rotation schedule, allowed URLs) lives on disk, in plain 0600 JSON.

disabled flag — the code path does not exist.

• There is no secretread tool**, and no CLI command that echoes a value to stdout. Not a

• The one route to the outside world, secret_use, can only reach URLs you pre-approved per entry.

Quick start

pip install keystash          # or: uv tool install keystash

keystash doctor               # check Keychain / osascript / security / pbcopy

# Store a key. The value is typed into a native hidden dialog — never argv, never the shell history.
keystash add OPENAI_PROD_KEY -a https://api.openai.com/ -r 90

# Let keystash invent one instead; it prints a fingerprint, never the value.
keystash generate STRIPE_PROD_SECRET -a https://api.stripe.com/ -r 180
# generated STRIPE_PROD_SECRET  sha256:1f3a9c02  (43 chars)

keystash list                 # metadata only
keystash list --json
keystash use OPENAI_PROD_KEY https://api.openai.com/v1/models
keystash rm OPENAI_PROD_KEY

Piping a value in (CI, another vault, a password manager export) skips the dialog:

printf '%s' "$VALUE" | keystash add MY_SERVICE_PROD_KEY --stdin -a https://api.myservice.com/

Naming convention: SERVICEENVPURPOSE — OPENAIPRODKEY, ALIYUNOSSSTAGINGSECRET. Enforced: ^[A-Z][A-Z0-9]{0,63}$.

Touch ID unlock

Values live in the login Keychain. keystash copy NAME puts the value on the clipboard and clears it again after 30 seconds (--clear-after 0 disables the clear). Nothing is printed. The Touch ID prompt appears when a value is actually needed — not on list, not on show, not on doctor, not on metadata edits.

keystash doctor — clean up the mess you already have

keystash doctor reports the platform, whether the Keychain backend is available, the paths of osascript / security / pbcopy, your metadata file, the audit log, and the legacy vault path. If the metadata file exists it also prints the entry count and which entries are past their rotation interval.

AI agents, zero plaintext: keystash mcp

keystash mcp speaks MCP over stdio only — it opens no socket, not even on 127.0.0.1. It exposes exactly six tools. There is no secretread, and no runcommand:

Wire it into an MCP client:

Shortened. The full README is on GitHub.