gpg-mcp

gpg-mcp

A security-focused Model Context Protocol server for GnuPG.

gpg-mcp lets an AI agent sign, verify, encrypt, decrypt and manage OpenPGP keys without ever receiving private key material. Private keys stay in gpg-agent; passphrases go only into pinentry; high-risk operations require an explicit human approval; destructive operations require typing a fingerprint suffix.

Threat model in one sentence: the MCP server is a policy boundary, not an OS sandbox. It

prevents the agent from *receiving* private keys and from silently using them. For protection

against an agent that already has shell access as the same OS user, run the signer as a separate

user or use a hardware token (see Stronger isolation).

Why this exists

Most “GPG MCP” wrappers are thin subprocess shells: any tool with a command: str parameter, or an agent that can ask for --export-secret-keys, defeats the point. gpg-mcp instead exposes a fixed, typed surface with deliberate omissions:

• No raw command execution. There is no run_gpg(args) tool.
• No secret-key export or backup. --export-secret-keys, --export-secret-subkeys and --export-secret-ssh-key are unreachable.
• No passphrase parameters. No --passphrase, --passphrase-fd, --passphrase-file, no loopback pinentry, no passphrase in environment variables or stdin.
• No `--homedir` override. The keyring is fixed by configuration.
• No short key IDs. Operations require full 40- or 64-hex fingerprints.
• No automatic key retrieval. Verification does not silently fetch keys from the network.
• No hidden recipients. Decryption preflights the ciphertext and refuses messages not addressed to an allowed key.
• A response guard. If gpg ever emits something that looks like private key material, the call fails and the output is dropped.

Security model

What the server guarantees

1. Private keys never cross the MCP boundary. Listing secret keys returns metadata only. Signing and decryption are performed by gpg-agent.
2. The server never sees a passphrase. --pinentry-mode ask is forced; pinentry talks to the human directly. The server cannot read the passphrase from argv, env or stdin.
3. Signing and decryption use allow-listed keys. With a shared ~/.gnupg, an empty allow-list denies both. With a dedicated keyring, the keyring itself is the allow-list boundary.
4. Decryption is recipient-checked. Before decrypting, gpg --list-packets is used to confirm the ciphertext is addressed to an allowed key. Hidden recipients are refused by default, even when the same message also has a visible allowed recipient.
5. Invalid embedded signatures abort decryption. If verify=true (default) and the decrypted message carries a bad, expired or revoked signature, the plaintext is not returned. valid is the policy result; the cryptographic result is reported separately. Multiple signatures are aggregated per NEWSIG sequence — or per packet on GnuPG without --proc-all-sigs — and fail closed if any signature is not policy-acceptable, regardless of event order.
6. Authorization is a fail-closed registry. Every high-risk tool names a registered operation. Unknown operations require approval. Composite operations (sign_and_encrypt, and encrypt with sign_with) inherit the approval requirement of every constituent, so a policy that gates only signing or only encryption cannot be bypassed.
7. Revocation certificates are validated before import. The certificate must contain a revocation signature, must reject secret-key packets, must target exactly the requested fingerprint, and must demonstrably revoke that key in an ephemeral keyring. apply=false is a true dry run and never touches the real keyring.
8. Destructive operations require typed confirmation. Deleting, revoking, or applying a revocation certificate requires the operator to type the last 8 characters of the fingerprint. This is controlled by destructive_confirmation and is independent of require_approval.
9. Every high-risk operation is audited. The ledger records operation names, fingerprints, payload SHA-256, size and the decision — never plaintext, payload previews or passphrases.
10. No shell. Commands are execve-style argv arrays. No shell interpolation, no option injection from user strings.
11. Minimal environment. LD_*, GPG_AGENT_INFO, GPG_TTY, SSH_AUTH_SOCK and other variables are not passed to gpg. Only the display/session variables pinentry needs are kept.
12. Sanitised binaries and paths. gpg, gpgconf and zenity are resolved to absolute paths, must be regular files, and must not be group/world writable. An unsafe zenity makes local approval fail closed instead of trusting a substituted dialog.
13. Bounded resources. Input/output size caps, per-operation timeouts, a dedicated process group killed on timeout, and a 0700 temporary directory with 0600 files. Status output beyond the effective status limit fails closed instead of being parsed partially.
14. The generic importer cannot revoke. import_public_key rejects secret-key packets and any revocation signature, including revocation signatures embedded in key material. Revocations must use import_revocation, where the target is validated and typed confirmation is required.
15. The actual decryption key is checked. After decryption, the DECRYPTION_KEY status must name an allowed primary or subkey; otherwise the plaintext is discarded. A ciphertext with an allowed visible recipient cannot silently decrypt through a different secret key.
16. GnuPG configuration is deterministic. The runner uses --no-options and --pinentry-mode ask, so a hostile gpg.conf cannot switch on loopback pinentry or change other security-relevant defaults.
17. Filesystem paths are checked without following symlinks. The config path is walked with directory file descriptors and O_NOFOLLOW, and the opened file is validated through fstat, so validation and use cannot race or be redirected by a path swap. The keyring path is kept unresolved (GNUPGHOME is not symlink-resolved); serve, doctor and init validate its full ancestor chain and reject a symlinked keyring or ancestor. Ancestors must be owned by the user or root and must not be group/world writable without the sticky bit. Unknown keys are rejected. Existing audit files are fstated, non-regular/foreign-owned files are refused, and group/other access is tightened to 0600. With audit_required = true, an audit failure fails the operation. init securely creates the config with O_EXCL|O_NOFOLLOW and refuses a symlinked gpg-agent.conf instead of writing through or chmodding its target. Missing config, keyring and audit directories are created component-by-component relative to already validated directory descriptors, so a symlinked ancestor cannot redirect or create anything before rejection. The audit path uses the same directory-fd walk, so an unsafe ancestor cannot redirect the ledger.
18. Decryption routing is unambiguous. symmetric_decrypt rejects hybrid ciphertext that also carries public-key recipients. decrypt rejects symmetric-only ciphertext and refuses to return plaintext unless GnuPG reports an actual allow-listed public key; it never falls back to the symmetric route. A custom policy that gates only symmetric_decrypt therefore cannot be bypassed through decrypt. For hybrid input, only GnuPG's recoverable symmetric-passphrase failure is tolerated, and only when a public key also reported DECRYPTION_KEY and DECRYPTION_OKAY; generic ERROR/FAILURE events and unexplained nonzero exit codes are rejected.
19. Multi-signature handling is fail-closed. Detached signatures use a per-packet fallback on GnuPG versions without --proc-all-sigs. Cleartext, inline, and embedded signatures use --proc-all-sigs when supported. On older GnuPG a bad-first message may stop enumeration at the first bad signature, but it is still rejected; all-good messages enumerate every signature.
20. Symmetric decryption is equally strict. It requires DECRYPTION_OKAY, rejects DECRYPTION_FAILED, BADMDC, ERROR and FAILURE, and treats unexplained nonzero exits as fatal. With verify=false, a nonzero exit is tolerated only for an explicitly recognized embedded-signature outcome; unrelated GnuPG failures are never excused.

Verification result semantics

verify (and the embedded-signature result returned by decrypt) separates four ideas:

Decryption releases plaintext only when every embedded signature is policy_acceptable. A mathematically valid but expired or revoked signature is never enough, and a bad signature cannot be hidden by a later good one. The result includes a signatures list with one entry per NEWSIG sequence.

What it does not guarantee

• Same-user isolation. Any process running as your OS user can read ~/.gnupg, connect to the gpg-agent socket, or edit ~/.config/gpg-mcp/config.toml. If the agent has shell access, the MCP policy is not an OS boundary. Use stronger isolation.
• A malicious MCP client. In approval = "client" mode, the client renders the approval dialog. A malicious client can fake it. Use approval = "local" (zenity, independent of the client) or a separate user/hardware token.
• Compromised gpg or gpg-agent. A compromised system binary can do anything. The binary checks reduce PATH hijacking, not supply-chain compromise.
• Semantic safety. The server can show *what* is being signed (hash and preview) but cannot judge whether the content is safe to sign. That judgement is the human's.

Threat table

| Agent hides one recipient among visible ones | Any hidde