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. 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.

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, and when it was last rotated. This lets the server list and rotate secrets without decrypting.
3. No in-place value update for generated or derived secrets. Those change only via rotation — the mutation model is deliberate, not accidental. External secrets (e.g. an upstream API key the user controls) can be updated with sops_update_external.

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.

Transforms (for derived secrets)

Tools

Creation and listing

Mutation (require SOPS_AGE_KEY)

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": "<your-age-public-key>"
      }
    }
  }
}

Environment variables

* One of SOPS_MCP_AGE_PUBLIC_KEY or SOPS_AGE_RECIPIENTS must be set.

Security

• No filesystem access — The server never reads from or writes to the client filesystem. All content is passed as text parameters and returned as text.
• No private key for normal use — Encryption uses only the public key. The private key is needed only for mutation tools.
• No plaintext in responses — Generated secret values are never returned. Derived values are returned because they're meant to be pasted into config files (e.g. an Authelia PBKDF2 hash) — don't derive values you don't intend to publish.
• Secure temp files — Used only for sops CLI invocation. Created with 0600 permissions, overwritten with zeros before deletion, cleanup guaranteed by finally block.
• OS-level entropy — Secret generation uses Python's secrets module (backed by /dev/urandom).
• stdio transport by default — No network exposure; runs as a client child process.
• Input validation — Key names must match ^[A-Z][A-Z0-9_]*$.

Encrypted file format