secrets-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@secrets-mcp-server Use my stored github_token to check the GitHub API rate limit."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
secrets-mcp-server
An MCP server for storing secrets (API keys, tokens, credentials) encrypted
at rest on your own machine, built so an AI agent can manage them without
the plaintext value ever entering its context. There is no get_secret
tool that returns a value as text — that was a deliberate design decision,
not an oversight. Using a secret is always indirect: run a command with the
value injected into its environment, or write the value straight into a
destination file.
Why
Giving an agent free-form shell access to your .env files means every
secret it touches can end up echoed back into its own transcript, its logs,
or a chat history — anywhere from a debugging session to a support ticket.
This server keeps secrets in one encrypted store and only exposes them
through two narrow, auditable operations: inject-into-subprocess and
write-to-file. The agent can use a secret to authenticate a request or
populate a config file; it can never see, print, or leak the raw value
through a normal tool call.
Related MCP server: enigmagent-mcp
Tools
Category | Tool | Description |
CRUD |
| Creates a secret; fails if |
CRUD |
| Creates several at once ( |
CRUD |
| Reads a |
CRUD |
| Overwrites the value; fails if the secret doesn't exist |
CRUD |
| Removes a secret |
CRUD |
| Lists name/description/timestamps for every secret. Never includes the value |
Opaque use |
| Runs |
Opaque use |
| Writes one or more secrets straight into |
run_with_secret never uses a shell (shell=False, command is a list of
args) — this avoids command injection even if an argument comes from
untrusted text.
apply_secrets_to_file only writes inside directories listed in
SECRETS_MCP_ALLOWED_WRITE_DIRS — without that configured, every write is
rejected.
import_secrets_from_file can read any file the process has OS permission
to read — this is a deliberate choice, with no read-side allowlist (unlike
writes). If you need to restrict that, add a
SECRETS_MCP_ALLOWED_READ_DIRS check following the same pattern as
validate_dest_path in security.py.
Environment variables
Variable | Default | Purpose |
| (required) | Passphrase used to derive the store's encryption key. Without it, the server refuses every operation |
|
| Where the encrypted store file lives |
| (empty) | Comma-separated list of directories |
|
| Timeout for |
Security model
The store is a single file (
salt+ ciphertext) encrypted as a whole with Fernet (cryptography); the key is derived from the passphrase via Scrypt with a fresh random salt on every write. A wrong passphrase or a corrupted file fails loudly — there is no silent fallback.The store file and any file written by
apply_secrets_to_fileend up with0600permissions.run_with_secretnever usesshell=True;commandis always a list of args, never a shell string.apply_secrets_to_fileresolves the destination path (realpath, following symlinks) and rejects anything outsideSECRETS_MCP_ALLOWED_WRITE_DIRS.No tool logs or returns a raw value.
run_with_secretdoes a best-effort redaction (security.redact) that strips literal occurrences of the value fromstdout/stderrin case the command echoes it by accident — this is not a guarantee against every leak (e.g. a command that writes the value to a file outside this tool's control), but it covers the common case.
Requirements
Python 3.11+
uvto install dependencies and run the server
Installation
From PyPI, no clone needed:
uvx secrets-mcp-serveror install it as a persistent CLI tool:
uv tool install secrets-mcp-server
# or: pipx install secrets-mcp-serverFrom source, for local development:
git clone https://github.com/KauaLealz/secrets-mcp-server.git
cd secrets-mcp-server
uv syncRegistering with Claude Code
Using the published package (no clone required):
claude mcp add --scope user secrets \
--env SECRETS_MCP_MASTER_PASSPHRASE=<your-passphrase> \
--env SECRETS_MCP_ALLOWED_WRITE_DIRS=/path/to/your/projects \
-- uvx secrets-mcp-serverUsing a local clone instead:
claude mcp add --scope user secrets \
--env SECRETS_MCP_MASTER_PASSPHRASE=<your-passphrase> \
--env SECRETS_MCP_ALLOWED_WRITE_DIRS=/path/to/your/projects \
-- uv run --directory /path/to/secrets-mcp-server secrets-mcp-serverReplace /path/to/your/projects with whichever directories
apply_secrets_to_file should be allowed to write into (comma-separated for
more than one), and /path/to/secrets-mcp-server with wherever you cloned
the repo, if using the local-clone form.
--scope user makes it available in every Claude Code session. Changing
the passphrase between registrations produces a different store (the
encryption key depends on it) — keep the same passphrase to keep accessing
an existing store, and store it somewhere safe (a password manager). There
is no recovery if you lose it.
A .env.example is included as a reference for every variable below — it
is not auto-loaded, it just documents the shape a .env for this project
would take if you build tooling around it.
Registering with other MCP clients
Any MCP client that supports stdio servers can run this the same way:
launch uvx secrets-mcp-server (or uv run --directory /path/to/secrets-mcp-server secrets-mcp-server
for a local clone) with the environment variables above set in its process
environment. Check your client's documentation for how it declares stdio
MCP servers (e.g. a mcpServers entry in its config file).
Tests
uv run pytestContributing
Issues and pull requests are welcome. See AGENTS.md for the design
constraint this project is built around (no tool ever returns a raw secret
value) — please keep new tools consistent with it, or open an issue to
discuss before changing it.
License
MIT — see LICENSE.
Available Tools
8 toolsapply_secrets_to_fileA
Writes one or more secrets into dest_path without ever returning the value. key_names is an optional {name: key_in_file} map — without an entry, it defaults to the secret name upper-cased (e.g. 'db-pass' -> 'DB_PASS').
Inputs: names (required), dest_path (required), format, key_names. Returns: result
create_secretD
Inputs: name (required), value (required), description. Returns: result
create_secrets_batchD
items: list of {"name": str, "value": str, "description": optional str}
Inputs: items (required). Returns: result
delete_secretD
Inputs: name (required). Returns: result
import_secrets_from_fileA
Reads a .env-style file (KEY=VALUE per line) and imports each key as a secret. name_pattern (regex) filters which keys get imported; prefix is prepended to the created secret name; overwrite controls whether existing secrets get updated.
Inputs: source_path (required), prefix, overwrite, name_pattern. Returns: result
list_secretsD
Inputs: no named parameters. Returns: result
run_with_secretD
Inputs: command (required), secret_name (required), cwd, timeout, +1 more. Returns: result
update_secretD
Inputs: name (required), value (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a clearly distinct operation: individual CRUD, batch creation, file import, and two separate consumption modes (file substitution vs command execution). There is no meaningful overlap or ambiguity between tool responsibilities.
Core operations follow a consistent verb_noun pattern such as create_secret, update_secret, delete_secret, and list_secrets. The batch, import, and application tools use slightly different phrasal forms, but they remain readable and predictable.
Eight tools is well-scoped for a secrets management server. It covers single operations, batch creation, file-based import, and secure usage without unnecessary redundancy or bloat.
The toolset provides full lifecycle coverage for secrets: create, update, delete, and list, with batch and import variants for efficiency. The absence of a plain get_secret action appears intentional for security and does not create a workflow dead end.
Related MCP Connectors
A secret store for AI agents: the agent never sees the plaintext.
Encrypted secret store and rotation for autonomous agent credentials
Secrets for developers and agents—secure context and workflows without exposing secret values.
Encrypted store for API keys and database URLs your code needs. Use them without reading them.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to write .env files with secrets stored locally, allowing search by name/description while keeping actual secret values private and never exposed to the AI.5MIT
- AlicenseAqualityBmaintenanceLocal AES-256-GCM encrypted vault for AI agents. Resolve {{PLACEHOLDER}} secrets in prompts at runtime — LLMs never see real API keys. Argon2id key derivation, zero cloud.270 npm7MIT
- AlicenseNot gradedqualityCmaintenanceEnables secure credential storage for AI agents by encrypting secrets and providing agent-invisible references, ensuring sensitive data never leaks to the model.MIT
- AlicenseNot gradedqualityDmaintenanceEncrypts and stores API keys and environment variables locally, providing them to AI agents via MCP with tools for listing, describing, getting secrets, and running commands with secret values redacted.2MIT