moltenmail-cli

A tiny, standalone command-line client and MCP server for MoltenMail — the read-only macOS email client with a local agent API. It talks to MoltenMail over a local Unix domain socket; it holds no credentials and has no email stack of its own. Its only dependency is Apple's swift-argument-parser.

App Store (sandboxed) builds of MoltenMail can't bundle a runnable helper, so this is distributed as a small signed download and used as your AI agent's MCP server.

What it does — and what it can't

This helper is a thin pipe: it forwards your agent's request to MoltenMail over the local socket and relays MoltenMail's reply. The capability limit — read mail and create reviewable drafts; never send, delete, move, or mark — is enforced by MoltenMail itself, which accepts only that fixed set of actions on the socket and rejects everything else. The full contract is in PROTOCOL.md.

You can confirm the helper doesn't widen that surface by reading the source:

• It holds no credentials, no Keychain, no IMAP/SMTP, and opens no network connection — the only I/O is the local agent.sock (AgentSocketClient.swift).
• It can't inject a different action: the request action is set from a fixed allowlist after arguments are merged, so a crafted argument can't smuggle in a destructive verb (AgentSocketClient.swift, MCPToolMapping.swift).
• There is no send/delete/expunge/move/mark path anywhere in the code. Draft/reply commands compose a reviewable draft (local by default, or the server Drafts folder with --server); they never send.

Install

App Store MoltenMail users — use the signed download

Download the signed, notarized moltenmail-cli.zip from https://moltenrock.com/downloads/moltenmail-cli.zip (setup guide: https://moltenrock.com/moltenmail), then:

mkdir -p ~/.local/bin
unzip -o ~/Downloads/moltenmail-cli.zip -d ~/.local/bin/
chmod +x ~/.local/bin/moltenmail-cli
~/.local/bin/moltenmail-cli accounts list   # verify: app → helper → socket → mailbox

The signed download is the supported path — Gatekeeper accepts it without extra steps.

Build from source — for developers

swift build -c release
.build/release/moltenmail-cli accounts list

A locally built binary is not signed by Goldcote, so macOS Gatekeeper will warn or block it until you sign it yourself (or clear quarantine). Building from source is for development and contribution, not the recommended install for App Store MoltenMail users.

Use as an MCP server

Point your MCP host (e.g. Claude Desktop) at the binary with the mcp subcommand:

{ "mcpServers": { "moltenmail": {
    "command": "/Users/you/.local/bin/moltenmail-cli",
    "args": ["mcp"] } } }

Per-message logging is off by default. Set MOLTENMAIL_MCP_DEBUG=1 to log received lines and tool names to stderr while debugging (these can contain account/folder/message ids, so leave it off in normal use).

Troubleshooting

Both Direct and App Store MoltenMail on one Mac? By default the helper prefers the non-sandboxed socket (~/.moltenmail/agent.sock), then the App Store container socket. To pin a specific build, set MOLTENMAIL_SOCKET to the absolute path MoltenMail shows in Settings → Local Agent Access:

export MOLTENMAIL_SOCKET="/absolute/path/shown/in/MoltenMail/agent.sock"

The override wins outright, with no fallback.

Documentation

• PROTOCOL.md — the socket + MCP contract (tools, actions, what is not a verb).
• RELEASE.md — how the signed, notarized, universal zip is built.
• SECURITY.md — reporting a vulnerability + threat model.
• CHANGELOG.md — versions and the bump rule.

License

MIT — see LICENSE. Copyright © 2026 Goldcote Ltd.