stash MCP server
Commit Nov 14, 2026Allows AI agents to access encrypted secrets and passwords via an MCP server with mandatory Touch ID approval for every use.
Also known as Mrlopez62/stash
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is stash MCP?
stash allows AI agents to access encrypted secrets and passwords via an MCP server with mandatory Touch ID approval for every use.
Summary generated from the project's README
About stash MCP server
Developers can grant AI agents access to encrypted secrets and passwords through this MCP server while maintaining strict security via mandatory Touch ID approval for every single use. This setup ensures that sensitive values never enter the model's context, protecting your data from being stored in chat histories or training sets.
Running locally on macOS, the server integrates with the stash Mac app and CLI to manage logins, 2FA codes, SSH keys, and payment cards. Users must build the software from source using Rust and Xcode Command Line Tools. Once configured, an AI agent like Claude Code can request specific secrets, but the user must physically approve the request with a fingerprint to proceed. This creates a secure bridge between your local encrypted vault and your AI coding tools without sacrificing privacy or manual control.
What you can do with it
- 1Securely providing API tokens to agentsAn AI agent can request a specific API key from your vault to complete a task, requiring your fingerprint to release it.
- 2Preventing secret leakage in chat historyYou can allow an AI to use your credentials without the actual secret values being written into the conversation context.
- 3Managing developer credentials locallyDevelopers can store and retrieve SSH keys and login credentials through a local encrypted vault instead of using unencrypted files.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
GITHUB_TOKENOPENAI_API_KEY
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablemrlopez62/stash is public and reachablegithub.com/mrlopez62/stash ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-07github.com/mrlopez62/stash ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubA free, open-source password and secrets manager for macOS, built for developers. Unlock with Touch ID, fill passwords and cards in your browser, sign git commits with keys kept inside the encrypted vault instead of ~/.ssh, pass API tokens into commands safely, and let AI agents use your secrets with your approval each time, without the values going into their context.
Status: early development (v0.19). Everything below works today:
- The stash Mac app: menu bar, Quick Access (⇧⌘Space), vault browser and editor
- Items: logins with 2FA codes, secrets, notes, payment cards and bank accounts, SSH keys
- Browser autofill in Chrome, Brave, Edge, Arc, and Firefox, with saving new logins and cards
- Developer tools:
stash://references,stash run,stash inject, an SSH agent with git commit signing- AI agents: an MCP server with Touch ID approval for every use, and an encrypted audit log
- The stash iPhone app: your logins, cards, and bank accounts, with Face ID, copied from your Mac or added on the phone
stash hasn't had an outside security review yet, so don't trust it with production secrets. There are no prebuilt downloads yet: you build it from source, which takes a few minutes.
The Mac app
git clone https://github.com/Mrlopez62/stash.git && cd stash
./scripts/build-app.sh --install # builds stash.app into ~/Applications
open ~/Applications/stash.app
- Vault browser. Search logins, secrets, notes, cards, bank accounts, and SSH keys, with copy buttons for every field and live 2FA codes with a countdown. Cards get a card face showing only the last four digits.
- Quick Access with ⇧⌘Space from anywhere. Type a few letters, press Return, and the password is on your clipboard.
- Menu bar icon. Quick Access, lock and unlock, open stash.
- Set up 2FA from the QR code. In a login's Two-factor field, choose Scan QR: stash reads the code straight off your screen, even from a window behind stash. You can also paste or drop a screenshot. It fills in the item's name and username from the code.
- Add a login's 2FA to your phone. The QR button on the one-time password shows a code that Google Authenticator, Authy, or the iOS Passwords app can scan. It never shows the secret as text, and it closes itself after a minute.
- Touch ID unlock and a built-in password generator. The app locks itself after 10 idle minutes.
- Safer copies. They're marked concealed, so clipboard-history apps skip them. They stay on this Mac (no Universal Clipboard) and are cleared after 30 seconds.
- The same vault as the CLI. Everything you add in the app works with
stash run,stash inject, and the MCP server, and the other way round.
Building needs Rust and the free Xcode Command Line Tools (xcode-select --install), not Xcode. The app is ad-hoc signed. If you build it yourself, macOS opens it normally.
The iPhone app
Keep your cards, bank accounts, and logins on your iPhone, unlocked with Face ID. Notes and SSH keys never go to the phone, and logins go only if you add them there or export them.
stash export --phone ~/Desktop/phone.stashvault # asks for Touch ID, then a password for the phone
./scripts/ios-install.sh # build and install the app on your plugged-in iPhone
Then AirDrop phone.stashvault to your iPhone and open it in stash (or, in Finder, drop it on your iPhone under Files → stash), unlock it with the password you chose, and delete the file from your Desktop. stash then asks whether to use Face ID from now on, and you can change that in Settings.
To bring your logins and their 2FA too, add --logins to the export. Exports copy only standard fields: never notes or custom fields.
No Mac vault to copy? Tap Skip on the first screen, choose a password, and add your logins, cards, and bank accounts on the phone. That vault exists only on that iPhone: it isn't in iCloud or any backup, and nothing syncs it to your Mac.
- What it does: shows your cards (with the same card face as the Mac app) and bank accounts, reveals a number or security code when you tap the eye, and copies values to the clipboard, where they stay on the phone (no Universal Clipboard) and clear after a minute. It locks as soon as you leave the app and hides itself in the app switcher. Settings (the gear) holds Face ID and replacing or removing the vault.
- A vault from your Mac is read-only: to change something, change it on your Mac and export again; opening the new file replaces the old one. Syncing is planned.
- Logins show their username and website, with the password hidden until you ask, and live 2FA codes. Set up 2FA by scanning a site's QR code or pasting its key. Copy them into the site or app: stash doesn't fill passwords on the iPhone yet.
- Card colors: choose a color for any card. It's saved in the vault on the phone, and doesn't show on the Mac.
- A vault made on the phone can have logins, cards, and bank accounts added, edited, and deleted there (swipe right on one to delete it). Opening a file from your Mac replaces it, after asking.
- Installing: needs Xcode (free) and an Apple ID: sign in under Xcode → Settings → Accounts, plug in your iPhone, and turn on Developer Mode (Settings → Privacy & Security). With a free Apple ID, Apple lets the app open for 7 days at a time: run
./scripts/ios-install.shagain to renew it; your cards stay on the phone. A paid developer account ($99/yr) makes it last a year. - Build for the simulator with
./scripts/ios-build.sh(needsbrew install xcodegen).
Getting started
Requires Rust 1.88 or newer. On macOS, the Touch ID helper also needs Xcode or the Command Line Tools (xcode-select --install).
git clone https://github.com/Mrlopez62/stash.git
cd stash
./scripts/install.sh # installs `stash` (and the Touch ID helper on macOS)
stash init # create a vault (asks for a new master password)
stash touchid enable # macOS: unlock with your fingerprint from now on
stash add github/token # prompts for the value without echoing it
stash add github --login --username octocat --url https://github.com --generate
echo "$OPENAI_KEY" | stash add openai/api-key # or pipe it in
stash ls # names only
stash get github/token # prints the value
stash get github/token --copy # copies it instead; cleared after 30s
stash otp github/2fa # current 2FA code (from an otpauth:// URI or base32 secret)
stash rm github/token
stash lock # end the unlocked session now
How unlocking works:
- The first command unlocks the vault. With Touch ID turned on, that's a fingerprint prompt. Otherwise you type the master password. If Touch ID is cancelled or unavailable (for example, the lid is closed), stash asks for the master password instead.
- Then a session starts, for that terminal only. stash commands you run from the same shell in the next 10 minutes don't ask again, and each use restarts the 10-minute timer. A small background agent holds the session, like
ssh-agent. Runstash lockto end it early. - Everything else has to ask. That includes commands started by
stash run, scripts, other terminals, and AI agents. They all get their own Touch ID prompt, which says what they want and who is asking, for example: stash is trying to unlock your vault for “get stripe/secret”, requested by sh ← stash, next to the stash icon. - Sessions pause while an AI agent runs. An AI coding agent that's allowed to script your terminal app could type
stashcommands into your unlocked shell. So while one is running (Claude Code, Codex, Gemini CLI, Cursor's agent, Aider, and others), every command asks for Touch ID again, and the prompt says why.stash agentsshows what's running. If you'd rather keep sessions,stash agents --allow-sessionsturns this off after a Touch ID check (--pause-sessionsturns it back on).
| Setting | What it does |
|---|---|
--vault <path> / STASH_VAULT |
Use a vault other than ~/.stash/vault.db |
STASH_SESSION_TIMEOUT |
How many seconds a session lasts without use. 0 turns sessions off |
STASH_PASSWORD |
Supply the master password for scripts and CI. This skips Touch ID and sessions. Any process that can read your environment can read it, so avoid it on your own machine |
Why
1Password is great for developers: the op CLI, op run, op:// secret references, Touch ID unlock, and the SSH agent make handling API tokens painless. But it's a paid subscription.
stash aims to give you that same developer workflow for free:
- Free and open source. No subscription, no account.
- Your data stays on your devices. One encrypted vault file, no account, no cloud. The iPhone gets only a separate file you copy over yourself, or a vault you make on it.
- Built for the terminal. Every feature works from the CLI first.
- A full password manager, too. A native Mac app, browser autofill, cards and bank accounts, and an SSH agent, all from the same vault.
- Ready for AI agents. A built-in MCP server lets tools like Claude Code use secrets without the secret values ending up in the model's context.
Not planned yet
- Team or family sharing
- Android, or a full vault on the iPhone (it holds logins, cards, and bank accounts for now)
- Cloud sync (planned for later as encrypted sync through iCloud Drive or Git; see the Roadmap)
Moving from another password manager
Export your passwords from the app you're leaving, then import the file:
| From | How to export | File |
|---|---|---|
| Chrome, Brave, Edge, Arc | Settings → Passwords (Password Manager) → Export passwords | .csv |
| Safari / Apple Passwords | Passwords app → File → Export All Passwords | .csv |
| Firefox | Settings → Passwords → ⋯ → Export Passwords | .csv |
| 1Password | File → Export → choose the 1PUX format | .1pux |
| Bitwarden | Tools → Export vault → .json (not "encrypted") |
.json |
| LastPass, Proton Pass, Dashlane, others | their CSV export | .csv |
stash import ~/Downloads/export.1pux --dry-run # what would come in, and under which names
stash import ~/Downloads/export.1pux # import it
In the Mac app, use File → Import Passwords… (⇧⌘I): you see every item first, with a checkbox for each, and import only the ones you keep checked.
- Logins come with their usernames, websites, notes, extra fields, and 2FA codes. Cards and bank accounts are checked like ones you add yourself; any that fail (a mistyped card number, say) are listed, never dropped silently. 1Password's Password and API Credential items come in as secrets. Notes, and kinds stash has no form for (like identities), come in as notes.
- Names come from each item's title and folder (
work/github), or its website. - Nothing in your vault is replaced. An identical item already there is left alone; a different one with the same name gets the new one named
github-2. - Delete the export when you're done. It holds every password in plain text. stash reads it once, writes nothing else to disk, and offers to delete it (
--delete-fileskips the question). In the app, it's deleted outright, not moved to the Trash. - Importing writes many items at once, so the CLI asks for Touch ID (or your master password) even in an unlocked session.
Use secrets in your projects
stash run: secrets for one command only
Put references instead of secret values in your .env file. It's safe to commit:
# .env
GITHUB_TOKEN=stash://github/token
OPENAI_API_KEY=stash://openai/api-key
PORT=3000
Then run your command through stash:
stash run --env-file .env -- npm start
✓ unlocked · injected 2 secrets into npm
> app@1.0.0 start · listening on :3000
- What gets replaced: any variable whose whole value is
stash://<name>is swapped for the secret, only inside that one command. Your shell, your history, and your files never hold the secret. - Where references come from: the current environment works too, for example
GITHUB_TOKEN=stash://github/token stash run -- gh repo list. Values from--env-filetake priority, and later files win. - Output masking: if the command prints a secret, stash replaces it with
<concealed by stash>. Use--no-maskingto turn this off. Values shorter than 4 characters aren't masked. - Ctrl-C and exit codes: both behave as if you ran the command directly.
- No unlock without references: if no references are found, stash runs the command without unlocking anything.
- New
.envfiles ask first: a.envfile in a repository you cloned was written by someone else, and it chooses which of your secrets the command gets. So the first time a file asks for secrets, and whenever the secrets it asks for change, stash asks for Touch ID (or your master password) naming the file and the secrets, even in an unlocked session. Changing plain values likePORTdoesn't ask again. Approve ahead of time withstash trust .env, and withdraw withstash trust --remove .env(orstash trust --resetfor all). Templates forstash inject -iwork the same way. WithSTASH_PASSWORDset (scripts and CI), files aren't asked about.
stash inject: fill in config templates
# config.tpl.yml (commit this)
database_url: {{ stash://db/url }}
api_key: {{ stash://openai/api-key }}
stash inject -i config.tpl.yml -o config.yml # config.yml is created readable only by you
stash inject < config.tpl.yml # or print to stdout
If any reference is missing, nothing is written. Existing files are only overwritten with --force.
stash get also accepts a reference: stash get stash://github/token.
Payment cards and bank accounts
stash add cards/visa --card --cardholder "Samus Aran" --expiry 08/27 # asks for the number and security code
stash add banks/chase --bank --bank-name Chase --routing 021000021 --account-type checking
stash get cards/visa # the card number
stash get cards/visa#cvv # also #expiry, #name, #zip
stash ls --long # "Visa •••• 4242 · 08/27"
- Typos are caught before they're saved. Card numbers must pass their Luhn checksum and match the brand's length, and expiry must be a real MM/YY no more than 20 years away (an expired card gets a warning but can be kept). Routing numbers are checked with the ABA checksum and IBANs with mod-97.
- Last four only in lists.
show,ls --long, and the app show just the last four digits until you reveal. In the app, a card gets a card face. - Off-limits to AI agents by default.
stash mcpwon't list or use cards and bank accounts unless you start it with--allow-payments. Blocked attempts go in the audit log.
SSH keys and git commit signing
Keep SSH keys in the vault instead of ~/.ssh. The stash SSH agent hands them to ssh and git, and every signature asks for Touch ID.
stash ssh generate ssh/github # a new Ed25519 key; prints the public key for GitHub
stash ssh import ssh/work ~/.ssh/id_ed25519 # or move an existing key in (asks for its passphrase)
stash ssh install # run the agent at login, and print the ~/.ssh/config line
stash ssh git-setup ssh/github --global # sign every commit and tag with it
Then add the IdentityAgent line that install prints to the top of ~/.ssh/config, and ssh, git push, and git commit use your stash keys.
- Touch ID per signature, on a prompt that names the key, what it's for ("log in as git", "sign a git commit"), and the process asking.
- Private keys never leave stash. Not to disk, not to AI agents:
stash mcprefuses SSH keys outright, since commands that need them get them through the agent. - Ed25519 keys, in OpenSSH's format. Keys made by stash work with
ssh-keygen, andssh-keygenkeys (including passphrase-protected ones) import into stash. - Every signature is logged in the audit log (
stash audit), by key name.
Browser autofill
Fill sign-in forms and checkout pages from the vault, in Chrome, Brave, Edge, Arc, and Firefox.
stash browser install # connects your browsers, then shows how to load the extension
Click the stash icon in the toolbar (or press ⌘⇧L) on a page: you'll see the logins saved for that site, plus your cards and bank accounts. Pick one and stash fills it in.
- Logins only fill on their own site.
github.com.evil.ionever gets your GitHub password; it isn't even suggested. Pages must be https (exceptlocalhost). - Every card or bank fill asks for Touch ID, on a prompt that names the card and the site.
- Nothing fills by itself. Only your click in the stash popup fills a page, and the extension can only touch the tab you clicked it on. Hidden fields are never filled.
- 2FA codes too: on a sign-in page's 2FA step, the same pick fills the current code.
- No secrets in the browser. The extension holds no data; it asks the vault for one item at a time, right before filling.
Optional: stash in sign-in fields, and saving logins. In the extension's Settings, turn on Show stash in sign-in fields. A stash icon then appears in username and password fields, and after you sign in or sign up, stash offers to save the login (or to update a password you changed, keeping the old one in the item). At checkout, it offers to save a new card (with Touch ID). It's off by default because it needs access to the sites you visit; with it off, stash only touches the tab whose toolbar button you click.
Logins, notes, and passwords
Items come in three kinds: a single secret (an API token), a login (username, password, website, optional 2FA), or a note.
stash add github --login --username octocat --url https://github.com --generate
stash add github --login --otp # type the password, then paste the 2FA secret
stash add notes/wifi --note
stash show github # fields, with passwords and codes hidden
stash show github --reveal
stash ls --long # kind, username, website, 2FA for every item
stash edit github --generate # new random password
stash edit github --otp # add or replace 2FA
stash edit github --set recovery-email=me@example.com --unset website
stash generate --length 32 --no-symbols # just a password
Reference one field with #:
stash://githubis a login's password, so existing references keep working.stash://github#usernameis its username.stash://github#otpis the current 2FA code.
These work everywhere references do: stash get github#username, .env files for stash run, stash inject templates, and the MCP server.
Passwords, 2FA secrets, and notes are only ever read from a hidden prompt or stdin, never from flags, so they stay out of your shell history.
--setis for visible fields only. It refuses password, 2FA, and notes fields, plus common secret-sounding labels liketoken,api key,client secret, andpin. That label check is a safety net, not a guarantee: never put a secret value on the command line. Store it as its own item and reference it.--seton a secret keeps it a secret. An API key with ascopefield is still an API key. Only--username,--url, and--otpturn an item into a login.- The note prompt reads one line. Pipe multi-line notes in instead:
stash add notes/x --note < notes.txt. - Generated passwords use the OS random number generator with uniform sampling and always include each enabled character type. Symbols like
$and#mean something in shells and some.envparsers, so quote them, or use--no-symbols. - Older vaults need one upgrade. A vault made before v0.6 can store logins and notes once you've unlocked it with your master password once. Until then, stash asks you to.
Clipboard and 2FA codes
stash get <name> --copyputs a secret on the clipboard instead of printing it.- On macOS, it's marked concealed so clipboard-history apps skip it, and it stays on this Mac (no Universal Clipboard), just like copies from the app.
- It's cleared after 30 seconds, but only if the clipboard still holds that secret, so something you've copied since is left alone.
STASH_CLIPBOARD_TIMEOUTchanges the delay, and0keeps the value.
stash otp <name>prints the current 2FA code, from a 2FA secret or a login's 2FA field. Add--copyto copy it instead.- Adding a 2FA item: store either the
otpauth://totp/...URI from the 2FA setup QR code or the base32 secret shown under "can't scan it?", withstash add github/2fa. - Code formats: 6–8 digits, any period, and SHA-1, SHA-256, or SHA-512, checked against the RFC 6238 test vectors.
- Adding a 2FA item: store either the
AI and MCP integration
stash mcp is an MCP server that lets AI agents like Claude Code and Cursor use your secrets without the values going into their context. A command written to transform a secret (base64, say) can still leak it in that form, so read what you approve; the threat model covers this.
stash MCP questions
How do AI agents use my secrets?
AI agents use an MCP server that requires Touch ID approval for every use, ensuring secret values do not enter the model's context.
Is stash safe for production secrets?
No, the project is in early development and has not yet undergone an external security review.
Can I use stash on my iPhone?
Yes, there is an iPhone app that supports logins, cards, and bank accounts using Face ID.
Does stash sync to the cloud?
Currently, it does not; data stays on your devices in an encrypted vault file, though encrypted sync via iCloud Drive or Git is planned.