# @mcpmastersh/mcpv > Offline, encrypted secrets for AI agents. Commit .env files full of mcpm:// references; `mcpv run` resolves them in memory, injects them into one process and masks its output — the agent never sees a value. Latest version **0.2.0** (published 2026-09-24) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install @mcpmastersh/mcpv pnpm add @mcpmastersh/mcpv yarn add @mcpmastersh/mcpv bun add @mcpmastersh/mcpv ``` Provides the command `mcpv`. ## Health **Score 60/100 (C)** — status: active. Positive: esm support; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads; no types; pre 1.0. ## Facts | | | |---|---| | Version | 0.2.0 | | Published | 2026-09-24 | | First published | 2026-09-24 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | none | | Module format | ESM | | Node | >=20 | | Dependencies | 0 | | Unpacked size | 98 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 0 | | Maintainers | mcpmastersh | | Keywords | secrets, dotenv, env, ai-agents, claude-code, mcp, vault, encryption | ## Links - npm: https://www.npmjs.com/package/@mcpmastersh/mcpv - Repository: https://github.com/mcpmastersh/mcpv - Homepage: https://github.com/mcpmastersh/mcpv#readme - Issues: https://github.com/mcpmastersh/mcpv/issues - npm.io page: https://npm.io/package/@mcpmastersh/mcpv ## Alternatives - [replicas-cli](https://npm.io/package/replicas-cli.md) — 3.0K weekly downloads - [env-contract](https://npm.io/package/env-contract.md) — 133 weekly downloads - [@openveo/api](https://npm.io/package/@openveo/api.md) — 61 weekly downloads - [@ryniaubenpm2/cumque-error-reiciendis](https://npm.io/package/@ryniaubenpm2/cumque-error-reiciendis.md) — 54 weekly downloads - [ts-global-type-extra](https://npm.io/package/ts-global-type-extra.md) — 11 weekly downloads ## Recent versions - 0.2.0 (latest) — 2026-09-24 - 0.1.0 — 2026-09-24 ## README # mcpv **Offline, encrypted secrets for AI agents: they can use them, but never see them.** AI coding agents like Claude Code are right not to handle raw secrets. A value pasted into a prompt ends up in the transcript, in logs, and possibly in a commit. `mcpv` keeps the values out of the agent's reach but still lets it run your app: ```bash # .env: commit it, paste it, let an agent read it. It holds addresses, not values. DATABASE_URL=mcpm://acme/api/dev/DATABASE_URL STRIPE_KEY=mcpm://acme/api/dev/STRIPE_KEY PORT=3000 ``` ```bash mcpv run -- npm run dev ``` `run` decrypts the references in memory and passes the values to that one process through its environment. It also scans everything the process prints and replaces secret values with `[redacted]`. The agent sees the command, the key names and the masked output. It never sees a value. No server, no account, no network. One encrypted file on your machine. ## Install ```bash npm i -g @mcpmastersh/mcpv # installs the `mcpv` command npx @mcpmastersh/mcpv doctor # or run it without installing ``` Needs Node 20 or newer. No runtime dependencies. ## Five commands you'll use ```bash # Move an existing .env into the vault and swap its values for references mcpv import .env --into mcpm://acme/api/dev --only DATABASE_URL,STRIPE_KEY --rewrite # Add or replace one secret. Type it at a hidden prompt, or pipe it in. mcpv set mcpm://acme/api/dev/OPENAI_API_KEY pbpaste | mcpv set mcpm://acme/api/dev/OPENAI_API_KEY # Run anything with ./.env resolved (or --env-file, or a whole --env environment) mcpv run -- npm test mcpv run --env mcpm://acme/api/prod -- ./migrate.sh # Safe for agents: key names only, never values mcpv check # does every reference in ./.env resolve? mcpv list # environments and key names ``` ## Web UI ```bash mcpv ui ``` This opens a local page in your browser. From it you can browse environments and key names, add or replace values, import a `.env`, delete secrets, and check that your project's `.env` references all resolve. It never shows a value, the same as the CLI. It only runs while you use it. It listens on 127.0.0.1 with a new token each time, and stops when you click Close, press Ctrl+C, or after 15 idle minutes. Nothing keeps running in the background. Also: `rm
` deletes a secret, `init` creates the vault, and `doctor` shows where the vault and its key are and whether it unlocks. `--json` works on `list`, `check` and `doctor`. ## Addresses ``` mcpm://// a whole environment mcpm:///// one secret ``` Workspace, project and environment are lowercase slugs. `KEY` is an environment variable name. This is the same format hosted [mcpmaster](https://mcpmaster.com) Agent Secrets uses, so a `.env` of references works with either. ## Using it with Claude Code (or any agent) Tell the agent how to run things, for example in the project instructions file Claude Code reads at startup: ```markdown Secrets are in mcpv. `.env` holds mcpm:// references, not values. Start anything that needs them with `mcpv run -- `. Never ask for secret values. `mcpv check` shows what's missing. If a key is missing, ask me to run `mcpv set
`. ``` Setting a secret needs you: values are only accepted from a hidden prompt or from stdin, never as command arguments, which end up in shell history, in `ps` and in agent transcripts. ## Security model **What is protected, and how** - **Encryption at rest.** Each value is encrypted with AES-256-GCM using a fresh IV. Its own address is bound in as additional authenticated data. If a ciphertext is moved to another key's slot, edited, or opened with the wrong key, it fails loudly. It never decrypts to the wrong value. - **The key lives somewhere else.** The master key is stored in the macOS Keychain or the Linux Secret Service (`secret-tool`) when available. Otherwise it goes in a `0600` key file. In CI, set `MCPV_KEY` (64 hex characters). On its own, `vault.json` is only ciphertext plus key names, whether it's in a backup, a synced folder, or a stray commit. - **No display surface.** No command prints a value, and no page of `mcpv ui` shows one. There is no `get` and no `reveal`. Values only go into a child process's environment. - **A locked-down local UI.** `mcpv ui` listens on 127.0.0.1 only, checks the Host header (which blocks DNS rebinding), and requires a per-run token that is never written to disk. It refuses cross-origin requests and non-JSON writes, sends a strict Content-Security-Policy, and shuts itself down when idle. - **Output masking.** `run` masks resolved values in the child's stdout and stderr, even when a value is split across two writes. Use `--no-mask` for fully interactive programs. - **No key inheritance.** The child process never receives `MCPV_KEY`. - **Private files.** The vault directory is `0700`. Its files are `0600` and are written atomically. **What it can't do.** Any process running as your user, an agent's shell included, can run `mcpv run -- printenv` with `--no-mask`, or read the key file, or ask the keychain for the key. Masking catches accidents, not a process that sets out to leak a value (it could base64-encode it first). Values shorter than 4 characters aren't masked, because masking them would shred the output. `run` warns when that happens. For a hard boundary, run the agent as a different OS user or in a container that has no access to the vault. This tool can't enforce that for you. ## Environment variables | Variable | Meaning | | --- | --- | | `MCPV_HOME` | Vault directory (default `~/.mcpv`) | | `MCPV_KEY` | Master key, 64 hex chars. Overrides the vault's own key store (for CI) | | `MCPV_PLAIN` / `MCPV_ASCII` / `NO_COLOR` | Terminal output: no decoration / ASCII glyphs / no color | | `MCPV_DEBUG=1` | Show stack traces for unexpected errors | ## As a library ```ts import { Vault, parseDotEnv, resolveDotEnv } from "@mcpmastersh/mcpv"; const vault = Vault.open(); const token = vault.resolveKey("mcpm://acme/api/dev/GITHUB_TOKEN"); // in memory, for your code to use ``` ## License Apache-2.0 --- _Source: https://npm.io/package/@mcpmastersh/mcpv · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._