The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Sops MCP listing page.
MCP server for creating and managing SOPS-encrypted secret files using age encryption.
Designed for Claude Code (or any MCP client) to produce encrypted secrets.enc.yaml files without the model ever seeing plaintext values. All file content is passed as text parameters and returned as text — the server has no filesystem access to the client.
Two goals drive the design:
1. Keep secrets in your source tree without leaking them. For a small project, running a full secrets manager (Vault, AWS Secrets Manager, etc.) is overkill for a handful of credentials. Encrypting secrets at rest in git and decrypting them in your CI/CD pipeline at deploy time is much cheaper:
secrets.enc.yaml via this server — age-encrypted against your public key, safe to commit.The age private key lives in exactly one place: your CI/CD secrets store. Everywhere else — your laptop, your git remote, your container images — sees only ciphertext. See the worked example below.
2. Let an AI coding agent generate secrets it can never read. Claude (or any MCP client) can create passwords, rotate them, derive hashes, rename and delete them — but plaintext values never cross the MCP boundary back to the model. The server holds the encryption key; the client only submits requests and receives metadata. There is deliberately no "decrypt this one secret" tool. If a prompt injection or a misbehaving agent tried to exfiltrate a secret via tool output, there is no tool output to exfiltrate.
This pattern assumes a single age recipient (the one CI private key). For multi-recipient / team key management, use the sops CLI directly for recipient rotations and this server for content management.
Three ideas shape the tool surface:
sops decrypt yourself with the age private key._meta_unencrypted block sits alongside the encrypted values (using SOPS's unencrypted_suffix feature) and records each secret's source, how it was generated, and when it was last rotated. This lets the server list and rotate secrets without decrypting.sops_update_external.Every secret is one of three sources, recorded in _meta_unencrypted:
generated — Cryptographically random values (Python secrets / OS CSPRNG). You specify length and charset; the server stores both so it can regenerate on rotation.external — User-provided values encrypted as-is (SMTP credentials, third-party API keys, etc.). Preserved across rotation. Updated via sops_update_external.derived — Computed from another key in the same file via a named transform. When the source is rotated (or an external source is updated), the derived value is automatically recomputed in topological order. Useful for things like Authelia's PBKDF2 hashes of OIDC client secrets.derived secrets)| Transform | Purpose | Deterministic |
|---|---|---|
pbkdf2_sha512_authelia | PBKDF2-SHA512 hash in Authelia's configuration.yml format ($pbkdf2-sha512$310000$...) | No — random salt per call |
sha256_hex | Hex-encoded SHA-256 digest | Yes |
| Tool | What it does |
|---|---|
sops_create_secrets | Create a new encrypted file with one or more secrets (any mix of sources). |
sops_list_secrets | List keys, sources, and descriptions from a file without decrypting. |
sops_create_oidc_secret | Convenience: create an Authelia OIDC client secret as a generated + derived (pbkdf2_sha512_authelia) pair in one call. The hash is returned in the response for pasting into configuration.yml. |
SOPS_AGE_KEY)| Tool | What it does |
|---|---|
sops_rotate_generated | Regenerate all generated secrets. Derived secrets whose source was rotated are recomputed; others are preserved. External secrets are preserved. |
sops_add_secrets | Add new secrets to an existing file. Supports all three sources. Rejects collisions with existing keys. |
sops_update_external | Replace the value of an external secret. Cascades to any derived secrets that reference it. Rejects attempts to update generated or derived. |
sops_rename_secret | Rename a key, preserving its value and metadata. Updates from: references in any derived secrets. |
sops_delete_secrets | Remove one or more keys. Rejects deleting a secret that another derived secret still references (unless the dependent is deleted in the same call). |
sops_add_metadata | Retrofit _meta_unencrypted onto a legacy SOPS file that lacks it. Supports generated, external, and derived entries. |
If you don't already have one, install age and run:
The file looks like:
age1...) — pass to this server as SOPS_MCP_AGE_PUBLIC_KEY. Safe to share anywhere.AGE-SECRET-KEY-...) — store as a CI/CD secret (commonly named SOPS_AGE_KEY). Never commit to source control. Anyone with this key can decrypt every secrets.enc.yaml encrypted to the matching public key.Back up the private key somewhere safe (password manager, hardware token). Losing it means losing access to every secret you've encrypted.
Add to your project's .mcp.json:
| Variable | Required | Purpose |
|---|---|---|
SOPS_MCP_AGE_PUBLIC_KEY | Yes* | Age public key for encryption |
SOPS_AGE_RECIPIENTS | Yes* | Alternative to SOPS_MCP_AGE_PUBLIC_KEY |
SOPS_MCP_SOPS_BINARY | No | Path to sops binary (default: sops) |
SOPS_MCP_LOG_LEVEL | No | Log level (default: WARNING) |
SOPS_AGE_KEY | Sometimes | Age private key — required for any mutation tool (rotate, add, update, rename, delete) |
SOPS_MCP_TRANSPORT | No | stdio (default) or sse |
SOPS_MCP_HOST / SOPS_MCP_PORT | No | Bind host/port for SSE transport (default: 127.0.0.1:55090). Binding to 0.0.0.0 requires SOPS_MCP_API_TOKEN — the server refuses to start otherwise. |
SOPS_MCP_ALLOWED_HOSTS | No | Comma-separated allowlist for the SSE Host header (DNS rebinding protection). Default: 127.0.0.1,127.0.0.1:*,localhost,localhost:*. Set explicitly when binding to a non-loopback address — e.g. mcp.example.com,mcp.example.com:*. |
SOPS_MCP_API_TOKEN | Sometimes | Required when SSE transport binds to 0.0.0.0; otherwise optional. When set, SSE requires Authorization: Bearer <token>. |
* One of SOPS_MCP_AGE_PUBLIC_KEY or SOPS_AGE_RECIPIENTS must be set.
finally block.secrets module (backed by /dev/urandom).^[A-Z][A-Z0-9_]*$.Secret values are AES-256-GCM encrypted. The _meta_unencrypted block is stored in plaintext (using SOPS's unencrypted_suffix feature) so metadata is readable without decryption.
Per-key read (decrypt-one-secret): intentionally absent. Returning plaintext over the MCP boundary would give the model access to secret material during tool calls — an accidental exfiltration vector. If you need a plaintext value, run sops decrypt yourself with the age private key.
Per-key in-place update for generated/derived secrets: intentionally absent. sops_rotate_generated is the one path that changes those values, so rotations leave an audit trail (last_rotated timestamp) and cascade cleanly to derived secrets.
Multi-recipient / team key management (.sops.yaml, updatekeys): planned for a future release. v1 assumes a single age recipient. For multi-recipient setups, use the sops CLI directly for recipient rotations and this server for content management.
Other source types (imported, templated): out of scope. Those are orchestration concerns — fetch values from Vault or compose URLs in your deployment templating layer, then pass the result here as an external secret.
The Docker build is hardened with three layers of verification, enforced by a CI gate.
The Dockerfile pins python:3.12-slim by SHA-256 digest (@sha256:...) so Docker always pulls the exact image that was audited, not whatever the slim tag currently points to. The digest and cosign signature status are tracked in base-images.lock.json.
Update the base image (when upstream publishes security patches):
The sops and age binaries downloaded in the Dockerfile are verified with sha256sum -c against checksums from the official release pages. A tampered binary fails the build.
Runtime dependencies are installed from requirements.lock.txt with pip install --require-hashes, which rejects any package whose content doesn't match the recorded SHA-256 hashes. This prevents dependency hijacking and typosquatting.
Update dependencies after editing requirements.in:
The supply-chain.yml workflow runs lib/verify_requirements.py and lib/verify_base_images.py on every push and PR. It checks that all lockfiles are well-formed and all Dockerfile FROM lines are digest-pinned.
Every container image published to GHCR is signed by this repo's publish workflow using keyless cosign via sigstore, and ships with SLSA v1.0 build provenance and an SPDX SBOM attached as OCI artifacts. Every commit on main and every release tag is SSH-signed. You can verify all of this without holding any long-lived key material — the signatures are anchored in sigstore's public transparency log.
Install cosign: https://docs.sigstore.dev/system_config/installation
Verify the image signature. A successful verification proves the image was built by this repository's publish.yml workflow, not just that its digest matches a reference someone sent you.
Inspect the attestations.
Verify git tags and commits. The simplest check is the green Verified badge on the github.com commits and tags pages.
A common pattern: use this server to produce secrets.enc.yaml files committed to your infrastructure repo, then decrypt them in CI and inject the plaintext values as environment variables to a container orchestrator (Portainer, Kubernetes, Nomad).
SOPS_AGE_KEY), the public key to Claude Code as SOPS_MCP_AGE_PUBLIC_KEY.secrets.enc.yaml with sops_create_secrets.sops decrypt secrets.enc.yaml > .env (or equivalent) and pass the result to your orchestrator.sops_rotate_generated or sops_update_external; commit and redeploy.The _meta_unencrypted block lets your tools filter out the metadata (keys starting with _) when pushing values to an orchestrator, so metadata never leaks into environment variables.
Apache-2.0. See LICENSE.