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. 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.
- 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.
- Read-only mode. One environment variable registers only the read tools — nothing that can change the mailbox is even advertised.
- Live API, no copy. No mailbox mirror or search index is stored anywhere; the only local state is your OAuth token.
| 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 |
modify_labels / bulk_modify | Label changes for one thread or for every message matching a query |
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; sweep on demand, via cron or hourly daemon |
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.