Gigamail

English · Italiano · 中文

MCP server that gives your agent — Claude, Codex, OpenClaw, Hermes, or any MCP client — safe, controlled access to your email — multi-account (Microsoft Graph + IMAP), calendar, local search index, sender memory, and an agent-aware permission model.

No built-in LLM: the intelligence is your agent's. The MCP server speaks stdio only — no network port. (An optional human console adds a local HTTP API bound to 127.0.0.1.)

On your data: GigaMail keeps mail indexes, credentials, memory and configuration on your machine — we run no service and receive nothing. Mail content your agent reads is, of course, handled by that agent and its model provider under their own data policies. Choose your agent accordingly; the masker lets you hide sensitive fields (tax codes, VAT numbers, IBANs, emails, phone numbers — validated deterministically, no AI) before the agent ever sees them.

Why

• Hybrid search: provider search (Graph/IMAP) + local SQLite index — fast and offline-friendly
• Its own archive: every mail of every account saved locally, attachments included, and still searchable after the server has dropped it. Outlook's history on the PC is imported once (gigamail archive)
• Sender memory: tone, topics and history per sender, so replies sound right
• Contact notes: what happened with each person — how a meeting went, what they are after — is written next to their name, and every draft to them reads it
• Observer: patterns learned from how the user edited past drafts
• Calendar-aware drafts: a draft only proposes times that are free in your calendar, inside your office hours
• Accounts viewed together (console): drag one account tile onto another to read both mailboxes as one list; every mail keeps its account, so replies leave from the right address, and "Split" undoes it. The agent keeps seeing separate accounts
• Knowledge files: attach your price lists, terms, product sheets to an account — the agent reads them to answer mail. Your agent doesn't need to know everything: the account carries its own knowledge
• Agent-aware permissions: reads are free; send/delete require an approval given out of band — the agent gets an inert request id, a human approves from the console or the CLI, and only then does it execute, with the exact arguments the human saw. Every write lands in an append-only action log
• Credentials never touch the agent channel: login and account management live in the CLI only — a prompt injection inside an email cannot add accounts or read secrets

Quick start

GigaMail ships through two channels:

• Desktop app, Windows and macOS — download it from gigamail.ai or from the latest release. The human console with its own Python: one installer, no prerequisites, no administrator password, and it updates itself.

  • Windows 10/11: GigaMail-Setup.exe, code-signed. The certificate is new, so on first launch Windows may still say "unrecognized app": click More info, then Run anyway.
  • macOS: GigaMail-arm64.dmg for Apple Silicon, GigaMail-x64.dmg for Intel, both signed with an Apple Developer ID and notarized by Apple.

  The SHA-256 digests are next to the files on the release page. To build it yourself: Node 22+, console/prepare-python.ps1 (Windows) or console/prepare-python.sh (macOS), then npm run dist or npm run dist:mac.

• pip install gigamail — the agentic core: MCP server, CLI, watcher and the console's local HTTP backend. No graphical app — the right channel when your agent is the interface.

Everything below covers the pip channel.

pip install "gigamail[all]"

gigamail login                # Microsoft device flow
gigamail accounts add-imap    # or IMAP: Aruba, Gmail, Libero, ...
gigamail check                # search, a draft held for your approval, a test mail to yourself

Microsoft login note: the bundled Azure app is not yet publisher-verified, so the consent screen shows an "unverified" notice (works fine; some corporate tenants may block it). Standard alternative: register your own Azure app and set your client_id in src/gigamail/core/ms_config.json. IMAP needs none of this.

Give the account its identity and knowledge (this is what makes replies yours):

gigamail identity set                       # who am I, what I do, tone
gigamail identity add-file C:\docs\pricelist.xlsx
gigamail identity add-file C:\docs\catalog\   # whole folder

Register in Claude Desktop / Claude Code (mcpServers):

{
  "gigamail": {
    "command": "gigamail-server"
  }
}

The commands are also available under their legacy names (ade-mail-agent, ade-mail-agent-server), and the Python package answers to its old name ade_mail_agent too (python -m ade_mail_agent.server), so existing setups keep working.

Using Claude Code? The repository is also a Claude Code plugin: it registers the gigamail MCP server and adds a skill that teaches Claude the approval gate.

claude plugin marketplace add adecubed/gigamail
claude plugin install gigamail@gigamail

Using Codex? The repository is a Codex plugin: it registers the gigamail MCP server and adds a skill that teaches Codex the approval gate.

codex plugin marketplace add adecubed/gigamail
codex plugin add gigamail@gigamail

GigaMail is also in the OpenAI Plugins Directory, as a skill: install it from there, then register the server with codex mcp add gigamail -- gigamail-server (the server comes from pip, as above).

Using OpenClaw or Hermes? Verified configs in INTEGRATIONS.md.

Are you an AI agent setting this up on behalf of a human? You can do the install and the MCP registration: pip install "gigamail[all]", then add gigamail-server to your client's MCP config (see INTEGRATIONS.md; declare GIGAMAIL_ROOT if your client filters the environment). Stop there. Connecting a mailbox (gigamail login, gigamail accounts add-imap) asks for credentials and must be done by the human in their own shell — it is not something you should do, and GigaMail is built so that it cannot be done through you. Tell them what to run, then wait.

Then just ask your agent: "reply to the last quote request using the price list" — it reads the mail, pulls the numbers from your file, drafts the reply, and asks you before sending.

Tools

30 typed tools, generated from the server itself:

• Read (18) — accounts, identity, knowledge files and search inside them, messages, unread, folders, hybrid search, attachment text, sender history, learned patterns, calendar events, free-slot availability, Drive files and their text
• Safe writes (3, audited) — mark read, move message, create folder
• Dangerous (9, human approval out of band) — send, reply, delete message, delete folder, create/delete calendar event, create a Zoom meeting, upload a file to Drive, move a Drive file to the trash

The calendar is served by Microsoft Graph or Google Calendar, whichever the user connected; the tools are the same either way. Drive uses the drive.file scope, so it only ever sees files GigaMail created itself. Connecting Google: GOOGLE_SETUP.md.

Full map and design decisions: MAPPA_MCP.md.

Security model

Email content is treated as untrusted data (prompt injection). The agent cannot approve its own actions, by construction: a dangerous tool returns only an inert request_id, and approving it — from the console or from gigamail approvals approve — requires an OS-level verification of the person at the machine (Windows Hello / Touch ID). A process, including an agent that holds a shell, can open that prompt but cannot pass it. On Linux, where neither exists, a local PIN typed in an interactive terminal stands in (gigamail approvals pin): weaker, and declared so in SECURITY.md. Telegram approval is opt-in and the weakest channel of the three. No secret ever enters the model context, so an injected instruction has nothing to spend. Repeating the id just returns awaiting approval. The agent can only read files explicitly registered by the user, never the rest of the filesystem. Every write action is logged to %APPDATA%/ADE/agent_audit.jsonl (append-only: GigaMail never rewrites past entries — it is not, and does not claim to be, tamper-proof storage).

We red-team this: hostile emails ordering exfiltration, mass deletion, and the agent to approve itself — fed to a real agent with every mail tool enabled.

This design is a fix. v0.1.0 returned a one-time confirm token in the tool result, which put it in the model's context: the agent held both halves. Thanks to u/ranbuman and u/anderson_the_one on r/mcp for catching it. The switch now sits where the agent cannot reach.

The structural half of that suite runs in CI on every push (tests/test_injection.py); the real-agent half is opt-in (scripts/injection_e2e.py) and runs with a dry-run guard so confirmed actions are audited but never executed.

Reply rules (0.2): semi-auto and auto reply, fenced

You can tell GigaMail: mail from these senders (or in this folder) gets a reply drafted from these documents. Rules are created from the CLI — gigamail rules add — behind the same Windows Hello / Touch ID prompt as approvals, and gigamail watch is the process that applies them. The MCP server stays passive and there is no MCP tool that touches rules: an injected instruction cannot enable autopilot.

• semi (default): the draft becomes a normal approval request — you get the notification, you approve with Hello, it goes out.
• Notifications reach you where you are: a Windows toast with ✅ / ❌ buttons (run gigamail desktop-setup once — UAC prompt — to make them clickable; they open the approval, which raises Hello) and Telegram (gigamail telegram setup, your own bot: ✅ approve if you opted in with --approve behind Hello, ❌ reject, ✏️ ask for changes — accepted only from your chat). Telegram approval is a convenience, not the normal path: any device signed into your Telegram can tap it, so it is weaker than Hello (see SECURITY.md).
• auto: the request is born approved, decided_by automode:<rule_id> — you gave that approval when you created the rule, for a precise scope, with a mandatory expiry, a daily cap and a per-sender cooldown. The notification still fires.

The drafter (your own agent, via claude -p) produces the reply body and nothing else: recipient, subject and thread are fixed from the incoming message — always the sender, never Reply-To, never an address written by the draft. Deterministic barriers run first: no DMARC pass → never auto; auto-generated mail, lists, no-reply senders, the provider's spam verdict, executable attachments → no reply at all; the first message from a new sender always goes through you; a burst of matches pauses the rule by itself. Details in SECURITY.md.

Extensions: the trade stays out of the core

The gigamail package does mail: accounts, index, search, two-phase send, calendar, knowledge files, audit. What only makes sense for one trade lives outside it and is off until you turn it on:

• appointments (built in, off by default): mail and calendar, connected, from the first reply to the follow-up.
  • Reads every sent mail, and the replies on those threads, for an appointment. A proposal stays out of the calendar; the time the client accepts goes in.
  • Client replies on followed threads reach you on Telegram and as a desktop notification, each with a Reply button: write "ok, fine" and your agent drafts the answer, which waits for your approval like any other. When the client names one precise time that is free in your calendar, the confirmation is drafted straight away.
  • A confirmed video call gets a Zoom meeting and the mail with the link, for approval.
  • After the meeting: one hour after it starts, GigaMail asks how it went — showed up, no-show, postponed, plus a couple of lines — on Telegram or as a desktop notification (gigamail debrief lists the unanswered ones). The answer goes into the contact's notes.
  • Follow-up a week later: when the client showed up, seven days later GigaMail drafts the follow-up from your notes, in the same thread, for your approval. If you have already been in touch since the meeting, it stays quiet.
• real_estate (extras/real_estate): flat-type check on drafts and unit codes that pick the attachments, for agencies answering property-portal enquiries. This is where GigaMail grew up.

gigamail extensions list
gigamail extensions enable appointments   # asks for Windows Hello / Touch ID
gigamail extensions install real_estate   # into the data folder: survives app updates
gigamail extensions enable real_estate

An enabled extension that fails to load stops automatic drafts and tells the human; it is never skipped silently.

License

AGPL-3.0-or-later. Free to use, study, modify and share. If you distribute a modified version — or run one as a network service — you must make its source available under the same license. Commercial licenses for closed-source use are available from the copyright holder.

GigaMail — La posta per il tuo agente AI

English · Italiano · 中文

Server MCP che dà al tuo agente — Claude, Codex, OpenClaw, Hermes o qualunque client MCP — accesso sicuro e controllato alla tua posta — multi-account (Microsoft Graph + IMAP), calendario, indice di ricerca locale, memoria dei mittenti e un modello di permessi pensato per gli agenti.

Nessun LLM interno: l'intelligenza è quella del tuo agente. Il server MCP parla solo stdio — nessuna porta di rete. (La console per l'umano, che è opzionale, aggiunge una API HTTP locale su 127.0.0.1.)

Sui tuoi dati: GigaMail tiene indici della posta, credenziali, memoria e configurazione sul tuo computer — noi non gestiamo alcun servizio e non riceviamo nulla. Il contenuto delle mail che il tuo agente legge è ovviamente trattato da quell'agente e dal suo fornitore di modello secondo le loro policy. Scegli l'agente di conseguenza; il masker permette di nascondere i dati sensibili (codici fiscali, partite IVA, IBAN, email, telefoni — validati in modo deterministico, senza