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-serverUse 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').
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes | ||
| format | No | env | |
| dest_path | Yes | ||
| key_names | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the behavioral disclosure burden. It does reveal the critical property that values are never returned and explains the default key-mapping behavior. However, it omits other important behavioral details such as whether dest_path is overwritten, what happens when a referenced secret doesn't exist, and how the format parameter affects the write.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences with the main action and security-critical behavior front-loaded. The key_names explanation with example is concise and high-value, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is strong on key_names and the non-return guarantee, and an output schema exists, so return values are covered. However, the missing format semantics and lack of file-overwrite behavior leave gaps that could cause incorrect calls, especially for non-env formats. Overall it's adequate for the most common path but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains dest_path, names implicitly as 'one or more secrets', and key_names in detail with an example. It does not mention the format parameter at all, which is a genuine gap given that schema description coverage is 0% and format has a default of 'env'. Thus it compensates for most parameters but leaves one key parameter obscure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action: writes one or more secrets into dest_path, and highlights a key behavioral trait (never returns the value). The operation is clearly distinct from sibling tools like create_secret/update_cret/list_crets because it targets a file path rather than managing the secret store.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives like import_secrets_from_file or run_with_secret. The description only states what the tool does, leaving the agent to infer the appropriate context. It doesn't mention exclusions, prerequisites, or when another sibling would be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_secretD
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| value | Yes | ||
| description | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_secrets_batchD
items: list of {"name": str, "value": str, "description": optional str}
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose the operation's effects, but it mentions no behavior at all. It does not state that secrets are created, whether existing secrets are overwritten, what authorization is required, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse, but this is under-specification rather than efficient conciseness. It omits the purpose and behavioral context that a tool description needs, so the single line does not earn its place as an adequate description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a batch creation tool with no annotations, the description is far from complete. It gives only the item payload shape and leaves the agent to infer the operation, scope, side effects, and appropriate usage from the tool name and siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only says items is an array of objects with additionalProperties true, so the description adds meaningful structure by specifying name, value, and optional description fields. It helps an agent construct valid input, though it stops short of explaining the meaning of each field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is only a data-format note ('items: list of...') and never states that the tool creates secrets or performs a batch operation. The tool name implies purpose, but the description itself provides no verb, resource, or functional statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus the siblings like create_secret or import_secrets_from_file. No conditions, exclusions, or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_secretD
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| prefix | No | ||
| overwrite | No | ||
| source_path | Yes | ||
| name_pattern | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose side effects itself. It does explain that overwrite controls whether existing secrets get updated, and describes prefixing and regex filtering. However, it does not state what happens when overwrite=false and a secret already exists, whether non-matching keys are silently skipped, or how malformed lines are handled. No annotation contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences: the first states the core operation and file format, the second systematically covers all three optional parameters. Every sentence earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the input file format and the semantics of each parameter, and an output schema exists for return values. It lacks edge-case behavior such as existing-secret handling when overwrite is false, handling of malformed lines, or file access assumptions, but for typical calls it gives enough to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining name_pattern as a regex filter, prefix as prepended to the secret name, and overwrite as controlling existing secret updates. source_path is only implied by 'Reads a .env-style file', not explicitly tied to the parameter, so a slight gap remains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear, specific action: reads a .env-style file and imports each key as a secret. It also names the filtering, prefixing, and overwrite behaviors, which clearly differentiates it from siblings like create_secret, create_secrets_batch, and apply_secrets_to_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for importing secrets from a .env-style file, but it gives no explicit guidance on when to choose it over alternatives like create_secrets_batch, nor any conditions or exclusions. The context is clear but the agent is left to infer the decision boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_secretsD
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_with_secretD
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | ||
| command | Yes | ||
| timeout | No | ||
| secret_name | Yes | ||
| env_var_name | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_secretD
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| value | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
8 tool updates
v0.1.0- First observed
apply_secrets_to_file - First observed
create_secret - First observed
create_secrets_batch - First observed
delete_secret - First observed
import_secrets_from_file - First observed
list_secrets - First observed
run_with_secret - First observed
update_secret
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.
Maintenance
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
- FlicenseNot gradedqualityCmaintenanceEnables 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.5-
- AlicenseAqualityDmaintenanceLocal 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.258 npm2MIT
- 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 gradedqualityCmaintenanceEncrypts 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