mailwarden — Gmail MCP Server for AI Assistants
mailwarden is a reliable, native Gmail MCP server — full mailbox triage for AI assistants such as Claude, with the feature nobody else ships: snooze. It talks straight to the live Gmail API (no cached mailbox snapshot) and re-verifies what Gmail’s sometimes-loose search index returns, so what your assistant sees is what is actually there.
Open source under the MIT license, written in TypeScript, published on npm. Install is a single command:
claude mcp add mailwarden -- npx -y mailwardenHighlights
- Snooze. Archive a thread now, have it resurface in the inbox on a date, a date + time, or a preset (
tomorrow 9am,weekend,next week,in 3 hours). Built on dated labels plus a sweep, so it works from any client and survives restarts — the Gmail API itself has no snooze. - Search you can trust. Gmail’s search index silently drops
is:unreadin some operator combinations; every hit is re-checked against its live labels and false positives are discarded. - Bulk operations that scale. Batch label changes for everything matching a query, 1000 messages per API request, with per-chunk partial-success reporting.
- Server-side auto-triage. Create, list and delete Gmail filters so the mailbox keeps triaging itself with no assistant in the loop — label-only actions, never forwarding, so there is still no exfiltration path.
- Triage digest. One read-only
triage_digesttool turns a mailbox slice into a decision-ready overview — top senders, label and age buckets, unread and attachment counts — instead of a raw thread list. - Structured outputs. Every tool declares an output schema and returns validated structured content — no parsing guesswork for clients.
- Correct with real-world mail. Encoded headers decoded, bodies decoded in their declared charset, rate limits retried with exponential backoff.
Security & privacy by design
- No send tools. mailwarden cannot compose, reply or forward — a prompt-injected instruction inside an e-mail has no exfiltration path through this server.
- No telemetry, no open ports by default. stdio only; an HTTP listener exists solely behind an explicit flag, optionally gated by a bearer token.
- Tool tiers & least scope.
MAILWARDEN_TOOLSadvertises only the tiers you name —read,manage,filters— and the OAuth scopes requested at authorization are derived from them, so a read-only deployment asks Google for nothing more thangmail.readonly.MAILWARDEN_READONLY=1is the read-only shorthand. - Token encryption at rest. Set
MAILWARDEN_TOKEN_PASSPHRASEand the stored OAuth token is AES-256-GCM-encrypted, so a copied or synced token file is useless without the passphrase. - Live API, no copy. No mailbox mirror or search index is stored anywhere; the only local state is your OAuth token.
Compared to other Gmail MCP servers
Several Gmail MCP servers exist. What stays mailwarden’s alone is not any single row below — it is snooze plus live re-verification together: an inbox-workflow layer over the mailbox’s current state, not over a snapshot.
| Capability | mailwarden | taylorwilsdon | Google official | mcpemails |
| Snooze (date / time / preset) | ✓ | — | — | — |
| Search-result re-verification | ✓ | — | — | — |
| Sweep / bulk over a query | ✓ | — | — | partial |
| No send tools (by design) | ✓ | sends | draft only | sends |
| Least-privilege tool tiers | ✓ | — | partial | partial |
| Token encryption at rest | ✓ | ✓ | n/a | ✓ |
| Fully local (no cloud copy) | ✓ | ✓ | — | — |
Comparison as of August 2026 against the then-current public versions; capabilities move, so treat it as a snapshot. The one recent shift: mcpemails added send and bulk — still no snooze.
Why re-verification matters — a concrete case
Ask an assistant to “archive the unread promotions that already scrolled past the inbox” and the obvious query is category:updates is:unread -in:inbox. Gmail’s search index silently drops the is:unread predicate in this combination and returns read mail as well. A server that trusts the index would archive already-read mail along with the rest — in a bulk action that is tedious to undo. mailwarden re-checks every hit against its reallabels and discards the index’s false positives before any action sees them.
| Tools | |
| Tool | What it does |
search | Gmail query syntax → thread summaries, read-state predicates re-verified, paginated |
get_thread | Full thread: headers, plaintext + HTML bodies, attachment metadata |
list_labels | All labels, system + user |
get_profile | Connected address + message/thread totals — confirm which mailbox is wired up |
triage_digest | Decision-ready overview of a mailbox slice: top senders, label + age buckets, unread and attachment counts |
create_label | Create a user label (idempotent, nested via Parent/Child) |
modify_labels / bulk_modify | Label changes for one thread or for every message matching a query — 1000 per API request, partial success reported per chunk |
archive, mark_read, mark_unread, trash, untrash | Everyday mailbox actions |
download_attachment | Save an attachment locally — fenced to a configured directory, never overwrites |
snooze, unsnooze, list_snoozed, sweep_snoozed | Archive now, resurface on a date, date + time or preset; sweep on demand, via cron or hourly daemon |
list_filters, create_filter, delete_filter | Server-side auto-triage rules (criteria → label actions only, never forwarding); optionally apply a new filter to existing mail |
Links
- Source & documentation: github.com/csitte/mailwarden (setup guide, changelog, issues)
- Package: npmjs.com/package/mailwarden
- Directory listings: Glama · CodeGuilds
mailwarden is developed and used in daily mailbox automation by C.Sitte Softwaretechnik. Contributions welcome.