Your real mailbox and calendar for your agent (M365/IMAP); a human approves every send.
GigaMail MCP Server (io.github.adecubed/gigamail)
GigaMail is an MCP server that provides “real mailbox and calendar” access for an AI agent using M365/IMAP. Its workflow is controlled: a human must approve every send. It targets MCP clients such as Claude, Codex, OpenClaw, Hermes, and other MCP clients.
🛠️ Key Features
Uses a real mailbox and calendar (M365/IMAP)
Human-in-the-loop control with approval required for sending
Categorized for MCP tool integration (mcp-tools / MCP)
🚀 Use Cases
Agent-assisted email and calendar interactions via M365/IMAP
Controlled outbound communication where a human approves sends
⚡ Developer Benefits
Works with MCP clients (e.g., Claude, Codex, OpenClaw, Hermes)
Designed around Model Context Protocol tooling (mcp, model-context-protocol)
⚠️ Limitations
Outbound messages require human approval before sending
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.
GigaMail
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.
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, Linux), then npm run dist,
npm run dist:mac or npm run dist:linux.
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.
bash
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):
bash
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):
json
{"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.
bash
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.
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
31 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, create folder, save a draft
Dangerous (10, human approval out of band) — move message, 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.
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.
bash
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.
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 AI) prima che l'agente
li veda.
GigaMail
Perché
Ricerca ibrida: provider (Graph/IMAP) + indice SQLite locale — veloce e
offline-friendly
Un archivio suo: ogni mail di ogni account salvata in locale,
allegati compresi, e cercabile anche quando il server non ce l'ha piu'.
Lo storico di Outlook sul PC si importa una volta (gigamail archive)
Memoria dei mittenti: tono, argomenti e storico per rispondere nel modo giusto
Note sui contatti: cosa e' successo con ogni persona — com'e' andato
un incontro, cosa cerca — resta scritto accanto al nome, e ogni bozza
per lei lo legge
Observer: pattern appresi dalle correzioni dell'utente alle bozze passate
Bozze che conoscono l'agenda: una bozza propone solo orari liberi nel
tuo calendario, dentro l'orario d'ufficio
Account visti insieme (console): trascina la tessera di un account
su un'altra per leggere le due caselle in un'unica lista; ogni mail
resta del suo account, quindi le risposte partono dall'indirizzo giusto,
e «Separa» torna indietro. L'agente continua a vedere account separati
File di conoscenza: collega listini, condizioni, schede prodotto a un
account — l'agente li legge per rispondere alle mail. Il tuo agente non
deve sapere tutto: le informazioni che gli servono viaggiano con l'account
Permessi per agenti: lettura libera; invio/cancellazione richiedono
un'approvazione data fuori banda — all'agente arriva solo un id
inerte, un umano approva dalla console o dalla CLI, e solo allora si
esegue, con gli argomenti esatti che l'umano ha visto. Ogni scrittura
finisce in un registro append-only
Credenziali fuori dal canale agente: login e gestione account solo via
CLI — una prompt injection dentro una mail non può aggiungere account né
leggere segreti
Setup rapido
GigaMail si installa da due canali:
App desktop, Windows e macOS — si scarica da
gigamail.ai o dall'ultima release. La
console umana con il suo Python incluso: un solo installer, nessun
prerequisito, nessuna password di amministratore, e si aggiorna da sola.
Windows 10/11: GigaMail-Setup.exe, firmato. Il
certificato è nuovo: al primo avvio Windows può ancora dire "app non
riconosciuta"; clicca Ulteriori informazioni, poi Esegui
comunque.
I digest SHA-256 sono accanto ai file nella pagina della release. Per
buildarla in casa: Node 22+, console/prepare-python.ps1 (Windows) o
console/prepare-python.sh (macOS, Linux), poi npm run dist,
npm run dist:mac o npm run dist:linux.
pip install gigamail — il core agentico: server MCP, CLI, watcher
e il backend HTTP locale della console. Nessuna app grafica — è il
canale giusto quando l'interfaccia è il tuo agente.
Tutto quello che segue riguarda il canale pip.
bash
pip install "gigamail[all]"
gigamail login # device flow Microsoft
gigamail accounts add-imap # oppure IMAP: Aruba, Gmail, Libero, ...
gigamail check # ricerca, bozza in attesa della tua approvazione, mail di prova a te stesso
Nota sul login Microsoft: l'app Azure inclusa non è ancora
publisher-verified, quindi la schermata di consenso mostra l'avviso
"unverified" (funziona comunque; alcuni tenant aziendali potrebbero
bloccarla). Alternativa standard: registra la tua app Azure e metti il
tuo client_id in src/gigamail/core/ms_config.json.
Per IMAP non serve nulla di tutto questo.
Dai all'account la sua identità e la sua conoscenza (è ciò che rende le
risposte tue):
bash
gigamail identity set# chi sono, cosa faccio, tono
gigamail identity add-file C:\docs\listino.xlsx
gigamail identity add-file C:\docs\catalogo\ # intera cartella
Registrazione in Claude Desktop / Claude Code (mcpServers):
json
{"gigamail":{"command":"gigamail-server"}}
I comandi restano disponibili anche con i vecchi nomi
(ade-mail-agent, ade-mail-agent-server), e il package Python risponde
anche al vecchio nome ade_mail_agent (python -m ade_mail_agent.server),
così le installazioni esistenti continuano a funzionare.
Usi Claude Code? Il repository è anche un plugin Claude Code: registra
il server MCP gigamail e aggiunge una skill che insegna a Claude il gate di
approvazione.
bash
claude plugin marketplace add adecubed/gigamail
claude plugin install gigamail@gigamail
Usi Codex? Il repository è un plugin Codex: registra il server MCP
gigamail e aggiunge una skill che insegna a Codex il gate di approvazione.
Usi OpenClaw o Hermes? Configurazioni verificate in
INTEGRATIONS.md.
Poi chiedi al tuo agente: "rispondi all'ultima richiesta di preventivo
usando il listino" — legge la mail, prende i numeri dal tuo file, prepara la
risposta e ti chiede conferma prima di inviare.
Tool
31 tool tipizzati, generati dal server stesso:
Lettura (18) — account, identità, file di conoscenza e ricerca al loro interno, messaggi, non
lette, cartelle, ricerca ibrida, testo degli allegati, storico mittenti,
pattern appresi, eventi di calendario, slot liberi, file di Drive e il
loro testo
Scritture sicure (3, con audit) — segna letto, crea cartella, salva una bozza
Pericolose (10, approvazione umana fuori banda) — spostamento,
invio, risposta, cancellazione messaggio, cancellazione cartella, creazione/cancellazione
evento, creazione di una riunione Zoom, caricamento di un file su Drive,
cestinamento di un file di Drive
Il calendario è servito da Microsoft Graph o da Google Calendar, secondo
quello che l'utente ha collegato: i tool sono gli stessi. Drive usa lo
scope drive.file, quindi vede solo i file creati da GigaMail.
Per collegare Google: GOOGLE_SETUP.md.
Mappa completa e decisioni di design: MAPPA_MCP.md.
Modello di sicurezza
Il contenuto delle email è trattato come dato non fidato (prompt
injection). L'agente non può approvare le proprie azioni, per costruzione:
un tool pericoloso restituisce solo un request_id inerte, e approvarlo —
dalla console o con gigamail approvals approve — richiede una verifica
dell'utente fisico a livello di sistema operativo (Windows Hello /
Touch ID). Un processo, compreso un agente con la shell, può aprire quel
prompt ma non superarlo; senza un backend del genere, nulla viene approvato.
Nessun segreto entra nel contesto del modello, quindi un'istruzione
iniettata non ha nulla da spendere. Ripetere
l'id restituisce solo in attesa di approvazione. L'agente può leggere solo i file
registrati esplicitamente dall'utente, mai il resto del filesystem. Ogni
azione di scrittura finisce in %APPDATA%/ADE/agent_audit.jsonl (append-only:
GigaMail non riscrive mai le voci passate — non è, e non pretende di essere,
un archivio a prova di manomissione).
Lo mettiamo alla prova: mail ostili che ordinano esfiltrazione,
cancellazione di massa e all'agente di approvarsi da solo, date a un agente
reale con tutti i tool attivi.
Questo disegno è una correzione. La v0.1.0 restituiva un token di conferma
monouso nel risultato del tool, quindi dentro il contesto del modello:
l'agente aveva entrambe le metà. Grazie a u/ranbuman e
u/anderson_the_one su r/mcp per averlo notato. Ora l'interruttore sta
dove l'agente non arriva.
La metà strutturale della suite gira in CI a ogni push
(tests/test_injection.py); quella con l'agente
reale è opt-in (scripts/injection_e2e.py) e usa
una modalità dry-run, così le azioni confermate finiscono nell'audit ma non
vengono mai eseguite.
Regole di risposta (0.2): semi-auto e auto reply, con recinto
Puoi dire a GigaMail: le mail da questi mittenti (o in questa cartella)
ricevono una risposta preparata da questi documenti. Le regole si creano
dalla CLI — gigamail rules add — dietro lo stesso prompt Windows Hello /
Touch ID delle approvazioni, e gigamail watch è il processo che le
applica. Il server MCP resta passivo e nessun tool MCP tocca le regole:
un'istruzione iniettata non può accendere l'autopilota.
semi (default): la bozza diventa una normale richiesta di
approvazione — arriva la notifica, approvi con Hello, parte.
Le notifiche ti raggiungono dove sei: toast Windows con bottoni
✅ / ❌ (una volta gigamail desktop-setup — prompt UAC — per renderli
cliccabili; aprono l'approvazione, che alza Hello) e Telegram
(gigamail telegram setup, col tuo bot: ✅ approva se hai scelto
--approve dietro Hello, ❌ rifiuta, ✏️ chiedi modifiche — accettati
solo dalla tua chat).
auto: la richiesta nasce già approvata, decided_by automode:<rule_id> — quell'approvazione l'hai data tu creando la regola,
per uno scope preciso, con scadenza obbligatoria, tetto giornaliero e
cooldown per mittente. La notifica parte comunque.
Chi scrive (il tuo agente, via claude -p) produce il corpo della
risposta e nient'altro: destinatario, oggetto e thread li fissa GigaMail
dal messaggio in arrivo — sempre il mittente, mai il Reply-To, mai un
indirizzo scritto dalla bozza. Prima passano barriere deterministiche:
niente DMARC pass → mai auto; posta automatica, liste, mittenti no-reply,
il verdetto spam del provider, allegati eseguibili → nessuna risposta; il
primo messaggio di un mittente nuovo passa sempre da te; una raffica di
match mette in pausa la regola da sola. Dettagli in
SECURITY.md.
Estensioni: il mestiere resta fuori dal core
Il pacchetto gigamail fa posta: account, indice, ricerca, invio a due
fasi, calendario, documenti, audit. Cio' che serve a un solo mestiere
vive fuori ed e' spento finche' non lo accendi:
appointments (incluso, spento di default): posta e calendario
collegati, dalla prima risposta al follow-up.
Legge ogni mail inviata, e le risposte su quei thread, in cerca di un
appuntamento. Una proposta resta fuori dal calendario; ci entra
l'orario che il cliente accetta.
Le risposte dei clienti sui thread seguiti arrivano su Telegram e
come notifica sul PC, entrambe con il bottone Rispondi: scrivi
«ok, va bene» e il tuo agente prepara la risposta, che aspetta la tua
approvazione come tutte le altre. Quando il cliente indica un orario
preciso e libero in agenda, la conferma si prepara da sola.
Una video call confermata riceve una riunione Zoom e la mail con il
link, da approvare.
Dopo l'incontro: un'ora dopo l'inizio GigaMail chiede com'e'
andato — si e' presentato, non si e' presentato, rimandato, piu' due
righe — su Telegram o con una notifica sul PC (gigamail debrief
elenca quelle senza risposta). La risposta finisce nelle note del
contatto.
Follow-up dopo una settimana: se il cliente si e' presentato,
sette giorni dopo GigaMail scrive il follow-up dalle tue note, nello
stesso thread, da approvare. Se nel frattempo vi siete gia' scritti,
non fa niente.
real_estate (extras/real_estate): controllo
della tipologia sulle bozze e codici delle unita' che scelgono gli
allegati, per le agenzie che rispondono ai portali. E' qui che GigaMail
e' nato.
bash
gigamail extensions list
gigamail extensions enable appointments # chiede Windows Hello / Touch ID
gigamail extensions install real_estate # nella cartella dati: resiste agli aggiornamenti
gigamail extensions enable real_estate
Un'estensione accesa che non si carica ferma le bozze automatiche e
avvisa l'umano: non viene mai saltata in silenzio.
Licenza
AGPL-3.0-or-later. Libero di usarlo, studiarlo, modificarlo e
condividerlo. Se distribuisci una versione modificata — o la offri come
servizio in rete — devi rendere disponibile il sorgente con la stessa
licenza. Licenze commerciali per usi closed-source sono disponibili dal
titolare del copyright.
SHA-256 摘要见发布页文件旁。自行构建:Node 22+,console/prepare-python.ps1
(Windows)或 console/prepare-python.sh(macOS、Linux),然后 npm run dist、
npm run dist:mac 或 npm run dist:linux。