mailhub-mcp

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_change reverts one batch exactly; undo_since is 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-admin on 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-only runs an instance with no write tools at all.
Your Google login only
Every request requires a Google login on the ALLOWED_EMAILS allowlist, 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.1 only. 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:

  1. access to private data,
  2. exposure to untrusted content,
  3. 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.modify scope 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.