Safe by construction, honest about the limits
Your mailbox is full of text written by strangers, and some of it will try to give your assistant orders. The server is built on the assumption that the model can be fooled.
Three guarantees
- Cannot send, trash or delete
- The code never calls Gmail's send, trash or delete methods, and a test scans the source to enforce it. Trash, Spam, Sent and Draft labels are refused.
- Every change is undoable
- Each organizing change is journaled with the labels messages had before.
undo_changereverts one batch exactly;undo_sinceis the panic button that reverts everything since a time. - Preview before bulk changes
- Changes by query show a match count and a sample first, and apply only with explicit confirmation, at most 500 messages per call.
More guards
- Reply-only drafts
- Drafts must answer a message, and may only be addressed to people already in that thread. Nothing is ever sent. Threads with a suspicious message are refused.
- Hidden text stripped
- Hidden HTML (
display:none, zero-size text, comments, scripts) and invisible or bidirectional control characters are removed before the model sees a message. - Untrusted content fenced
- Email text sits in one block per response, wrapped in markers with a fresh random nonce, so an email cannot forge the closing marker. The model is told nothing inside is an instruction.
- Suspicious messages flagged
- Heuristics flag likely injection attempts (tool names, "ignore previous instructions", requests to forward or draft, lots of hidden text). The model reports them and does not act on them.
- Attachments behind your login
- Attachment links last 14 days and open only after you sign in to
/admin. Spam, suspicious messages and file types Gmail blocks get no link. - Bill PDFs in a sandbox
- Only PDFs of messages that look like bills are read, in a separate process with memory, CPU and time limits. Only payment codes that pass their check digits, amounts and dates come back, never the PDF's text; the PIX code and payee are fenced like email text. Spam and suspicious messages get no billing data.
- Out-of-band approval
- Preferences that raise attention apply at once. Ones that lower it, like ignoring a sender, wait for you to approve them with
mailhub-adminon the server. No MCP tool can approve them. - Daily change cap and read-only mode
- At most 2000 messages changed per account per 24 hours by default, configurable with
MAX_CHANGES_PER_DAY(undo is never capped).TOOLS=read-onlyruns an instance with no write tools at all. - Your Google login only
- Every request requires a Google login on the
ALLOWED_EMAILSallowlist, and only allowed OAuth callbacks can register as clients. - Locked-down container
- Read-only filesystem, all capabilities dropped, a memory limit, and the port bound to
127.0.0.1only. See running it in Docker.
The lethal trifecta, and what mailhub can't fix
An AI agent becomes dangerous when it has all three of:
- access to private data,
- exposure to untrusted content,
- a way to send data out.
A mailbox is the first two by design. mailhub removes its own way out: it can't send mail, drafts only go to people already in the thread, and unsubscribe links are never visited.
But any other internet-capable tool in the same session (web fetch or search, a browser, a connector that posts messages, files or tickets) reopens the third leg, and the server can't see it. Choose which tools share a session with mailhub; for unattended routines, use TOOLS=read-only with no internet-capable tools alongside.
Limits
- The defenses are an aid, not a guarantee; see the known limitations.
- Gmail's
gmail.modifyscope technically permits sending; these protections live in the code, not the token. - What the assistant reads becomes part of your conversation, so it is sent to the provider of the model you use. With a local model, through an MCP client that runs it on your machine, email content never goes to an AI provider (untested; see clients).
- mailhub-mcp is beta software.
Full details and reports
Full details: the safety model in the README.
Please report vulnerabilities privately through the repository's Security tab (private vulnerability reporting), not in a public issue. Prompt-injection and sanitizer bypasses are in scope. See SECURITY.md.