Sops MCP

sops-mcp

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.

Why

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:

1. Create secrets.enc.yaml via this server — age-encrypted against your public key, safe to commit.
2. Commit it alongside your code.
3. Your CI/CD pipeline holds the age private key, decrypts at deploy time, and injects plaintext as environment variables into your container orchestrator.

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. This prevents a prompt injection or a misbehaving agent from exfiltrating a secret.

The simplest setup uses a single age recipient (the one CI private key). If you need several — a CI key plus an operator's key, or separate key sets for separate parties — see Key domains.

Secret sources

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.

Design

Three ideas shape the tool surface:

1. No plaintext crosses the MCP boundary. Generated secret values are never returned to the client. There is deliberately no "decrypt this one key" tool. If you need plaintext, run sops decrypt yourself with the age private key.
2. Metadata in plaintext. A _meta_unencrypted block sits alongside the encrypted values (using SOPS's unencrypted_suffix feature) and records each secret's source, how it was generated, when it was last rotated, and which key domain it belongs to. This lets the server list and rotate secrets without decrypting. SOPS's MAC covers these values by default, so a tampered block fails to decrypt. Files that switch that off with mac_only_encrypted are refused. Tools that read the block *without* a key still cannot check the MAC, which is why recipients are verified separately.
3. No in-place value update for `generated` or `derived` secrets. Those change only via rotation, where neither the server nor the caller has access to the plaintext. External secrets (e.g. an upstream API key the user controls) can be updated with sops_update_external.

Transforms (for derived secrets)

Tools

Creation and listing

Mutation (require a private key for the target domain)

Every tool takes a domain argument except sops_list_domains, which needs none. It is optional everywhere but sops_rekey, where it is required because the call changes who can read the file. See Key domains.

Setup

Prerequisites

• Python 3.11+
• sops CLI binary
• An age keypair (see below)

Generating an age keypair

If you don't already have one, install age and run:

age-keygen -o age-key.txt

The file looks like:

# created: 2026-04-22T12:34:56Z

public key: age1abc...xyz

AGE-SECRET-KEY-1HH...

• Public key (age1...) — pass to this server as SOPS_MCP_AGE_PUBLIC_KEY. Safe to share anywhere.
• Private key (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.

Installation

git clone <repo-url>

cd sops-mcp python3 -m venv .venv .venv/bin/pip install -e .

Claude Code configuration

Add to your project's .mcp.json:

{

"mcpServers": { "sops-mcp": { "command": "/path/to/sops-mcp/.venv/bin/python", "args": ["-m", "sops_mcp"], "env": { "SOPS_MCP_SOPS_BINARY": "/path/to/sops", "SOPS_MCP_AGE_PUBLIC_KEY": " " } } } }

Environment variables

\* One of SOPS_MCP_AGE_PUBLIC_KEY or SOPS_AGE_RECIPIENTS must be set, unless SOPS_MCP_DOMAINS_FILE or SOPS_MCP_DOMAINS supplies at least one domain. The server refuses to start with no domains at all.

Both recipient variables accept a comma-separated list, and SOPS_AGE_KEY accepts several newline-separated keys. Together they form the default domain.

Key domains

A domain is a named set of age recipients plus, optionally, the private keys the server holds for them. It is the unit the server encrypts to and decrypts with.

You do not need to configure one. The environment variables above become a domain called default, and a single-recipient setup never has to mention domains again.

Why they exist

Every mutation tool decrypts, changes, and re-encrypts. Re-encryption uses the server's configured recipients — so if a file was encrypted to a CI key *and* an operator key, but the server only knows about CI, the operator used to be dropped from the file silently. Domains fix that by making the recipient set a named, checked thing:

• A mutation compares the file's actual recipients against the domain's. If they differ it refuses, rather than quietly changing who can read the file.
• One server process can hold several independent key sets.
• sops_rekey performs a deliberate recipient change, which is the sops updatekeys workflow.

Several recipients, one domain

The common case needs no domains file. List every recipient in the usual variable:

SOPS_MCP_AGE_PUBLIC_KEY="age1ci...,age1operator..."

SOPS_AGE_KEY="AGE-SECRET-KEY-1CI..."

Files are now encrypted to both, and mutations keep both. The server only needs whichever private key it will actually decrypt with.

Several domains

Point SOPS_MCP_DOMAINS_FILE at a YAML file:

version: 1

domains: homelab: recipients:

• age1ci... # CI runner
• age1operator... # operator laptop keys:
• AGE-SECRET-KEY-1CI... client-acme: recipients:
• age1acme... key_f