mailwarden

# mailwarden

[![npm](https://img.shields.io/npm/v/mailwarden)](https://www.npmjs.com/package/mailwarden)
[![license](https://img.shields.io/npm/l/mailwarden)](LICENSE)
[![Node](https://img.shields.io/node/v/mailwarden)](package.json)
[![Website](https://img.shields.io/badge/Website-csitte.at%2Fmailwarden-2ea44f)](https://www.csitte.at/mailwarden/)
[![Smithery](https://img.shields.io/badge/Smithery-csitte%2Fmailwarden-ea580c)](https://smithery.ai/servers/csitte/mailwarden)

A reliable, **native** Gmail [MCP](https://modelcontextprotocol.io) server — full mailbox triage for AI assistants, with the feature no other Gmail MCP server ships: **mailbox-side snooze**.

## Highlights

- **Snooze — the only *mailbox-side* snooze in a Gmail MCP server.** Archive a thread now, have it
  resurface in the inbox on a date. Built on dated labels + a sweep, so it works from any client,
  is visible in Gmail itself, and survives restarts. (Where another server offers a "snooze", it is
  a local reminder list — the mail never leaves or re-enters the inbox.)
- **Search you can trust.** Gmail's `threads.list` — the call any thread search goes through — can
  answer `is:unread` from a **stale thread-level read state**: measured in one real mailbox, **86% of
  the threads it returned held no unread message at all**; in a second mailbox, no drift whatsoever.
  You cannot tell which mailbox you are in without looking, so `search` re-verifies every hit against
  its live labels. Paginated via `pageToken`/`nextPageToken`. ([the measurements](https://github.com/csitte/mailwarden/blob/main/docs/gmail-thread-read-state-drift.md))
- **Sender authentication, not sender spelling.** `get_thread` reports the SPF/DKIM/DMARC results
  the receiving server recorded, so "is this really from my bank?" is answered from the message's
  own headers instead of from how the domain looks. It reads the receiving server's report only —
  a message can carry forged ones of its own — and says `unchecked` when nobody checked, because a
  missing check is not a passing one.
- **Bulk operations that scale.** `bulk_modify` archives/labels everything matching a query at
  1000 messages per API request — with per-chunk partial-success reporting instead of
  all-or-nothing. The snooze sweep uses the same batch path.
- **Structured outputs.** Every tool declares an `outputSchema` and returns validated
  `structuredContent` alongside fenced JSON text — no parsing guesswork for clients. Failures are
  structured as well: a `code` and a `retryable` flag, so a client can tell "try again later" from
  "re-authorize" without reading prose.
- **Small attack surface.** No send tools (no exfiltration path for prompt-injected mail),
  optional read-only mode, no telemetry, no open ports by default, symlink-safe download fencing,
  injection-fenced output. And no code path that *could* send: every Gmail request passes an egress
  checkpoint that refuses `messages.send`, every draft endpoint, permanent deletion and forwarding
  settings, whatever a compromised or careless caller asks for. **One deliberate exception:**
  `unsubscribe` / `bulk_unsubscribe` (manage tier) contact the opt-out endpoint named in a message's
  own header — the only non-Google host mailwarden ever reaches, and a `read`-tier deployment makes
  no outbound request at all. Details under
  [Security & privacy](#security--privacy) and
  [Unsubscribing](#unsubscribing--the-one-outbound-request).
- **Correct with real-world mail.** RFC 2047 headers decoded (`=?UTF-8?B?…?=` → readable text),
  bodies decoded in their *declared* charset (no mojibake for ISO-8859-1/Shift_JIS mail),
  429/5xx retried with exponential backoff.

## Why

Connectors that sync or cache your mailbox can lag behind it — and even Gmail's own search index is sometimes loose (see below). `mailwarden` talks straight to the live Gmail API (no cached snapshot) and re-verifies what the index returns, so what you see is what's actually there. It's a generic Gmail capability layer — keep your own rules/logic in your AI client, not in the server.

`search` goes one step further than the raw API: Gmail's `threads.list` index can answer read-state operators from a **stale copy** of that state, so `is:unread` returns threads you finished reading weeks ago — in one measured mailbox, the large majority of what came back. Since every hit is fetched live anyway, `search` re-checks the unambiguous predicates (`is:unread`/`is:read`/`is:starred`/`in:inbox`/`category:…`, with negation) against each thread's true labels and drops the index's false positives.

## Compared to other Gmail MCP servers

Most Gmail MCP servers cover the same read/label/send surface. Three capabilities are still unique to `mailwarden` (mailbox-side snooze, search re-verification, sender authentication), and one deliberate omission is a security feature, not a gap. Google's own server is also narrower than it looks: draft-only, and no trash, filters or unsubscribe.

<!-- comparison-table-verified: 2026-08-31 -->

| Capability | **mailwarden** | [Google official](https://developers.google.com/workspace/gmail/api/guides/configure-mcp-server) | [taylorwilsdon](https://github.com/taylorwilsdon/google_workspace_mcp) | [a-bonus](https://github.com/a-bonus/google-docs-mcp) | [klodr](https://github.com/klodr/gmail-mcp) |
|---|:--:|:--:|:--:|:--:|:--:|
| **Mailbox-side snooze** — archive now, resurface in the inbox on a date/time or preset | ✅ | — | — | — | — |
| **Search-result re-verification** — drops the thread index's false positives against live labels | ✅ | — | — | — | — |
| **Sender authentication** — SPF/DKIM/DMARC as the receiving server recorded them, on every message | ✅ first header only, values token-validated | — | — | — | — |
| **Sweep / bulk over a query** — one action across every thread a search returns | ✅ 1000/req, partial-success | — | ⚠️ batch by explicit ids | — | ⚠️ batch by explicit ids |
| **Unsubscribe** — per-sender overview + RFC 8058 one-click opt-out, no send scope needed | ✅ | — | ⚠️ header shown, no action | — | — |
| **Inbox triage overview** — one call that buckets what is waiting | ✅ sender/label/age + header signals | — | — | ✅ heuristic flags + stats | — |
| **Server-side filters** — rules that keep triaging with no assistant in the loop | ✅ never forwarding | — | ✅ | — | ✅ |
| **No send tools — by design** — a prompt-injected mail has no exfiltration path | ✅ no compose at all | ⚠️ draft-only | ❌ sends | ❌ sends | ❌ sends |
| **Least-privilege tool tiers** — OAuth scopes derived from the tools you enable | ✅ | ⚠️ scope split | ⚠️ `--read-only` narrows scopes; tiers narrow tools only | — | ⚠️ inverse: tools gated by granted scopes |
| **Token encryption at rest** | ✅ AES-256-GCM, **opt-in** (`MAILWARDEN_TOKEN_PASSPHRASE`) | n/a (hosted) | ⚠️ file mode `0600`; bucket CMEK on GCS | — | — |
| **No vendor cloud — you operate the server** | ✅ | ❌ Google-hosted | ✅ | ✅ | ✅ |
| **Structured outputs** — every tool declares an `outputSchema` | ✅ | — | — | — | ⚠️ one tool (`download_email`), more planned |

<sub>Snapshot as of 31 August 2026, from each project's public docs and source, with the sender-authentication row added on 2 September against each project's HEAD of that day; `—` = not offered / not documented. Columns are the servers a reader is most likely to reach for — Google's first-party one, plus the two largest community servers — and `klodr`, which comes closest to `mailwarden`'s own least-privilege design. Send capability is listed as a security property: `mailwarden`'s lack of it is intentional (see [Security & privacy](#security--privacy)). The encryption row asks who holds the key: `mailwarden` encrypts the token itself from a passphrase you set — and does nothing without one, which is why the cell says opt-in rather than showing a bare tick; `taylorwilsdon` relies on file permissions locally and on the storage bucket's own CMEK when hosted on GCS — protection against a stolen file in the first case, against a stolen disk in the second. The last row asks who *operates* the server, not where it happens to run: self-hosting is common ground here, and every community server on this table offers some remote deployment except `klodr` (stdio only) — `mailwarden` via `--http`, `taylorwilsdon` over streamable HTTP with OAuth 2.1, `a-bonus` on Cloud Run. Running one of them on your own host is not a cloud copy; running it on the vendor's is.</sub>

The moat isn't any single row — it's **snooze + live re-verification together**: an actual inbox-workflow layer that acts on the mailbox's *current* state, not a cached snapshot. Where others have caught up it's noted honestly above: at-rest encryption (`taylorwilsdon`), scope-driven tool gating (`klodr` inversely; `taylorwilsdon` in our direction but not as far — his `--read-only` really does switch the OAuth flow to the read-only scope map, but the requested set is built per *service*, not per tool, so a tier narrows which tools register without narrowing what the token may do: `--tool-tier core --tools gmail` still asks for the full Gmail scopes. Checked in his `auth/scopes.py` and `main.py` on 26 August 2026, and corrected there the same day by csitte.at, who verified it against their own clone rather than taking our word for it), a richer per-message triage heuristic (`a-bonus`), and bulk organize over a mailbox (the hosted mcpemails.com, which has no snooze either). What none of them do is act on a *query* and check the mailbox's answer before acting on it.

### Running it next to a Workspace server

`mailwarden` is a Gmail server, not a Workspace suite — if you want Calendar, Drive, Docs and Sheets
from one place, a broad server like `taylorwilsdon/google_workspace_mcp` covers ground this one never
will, and the two are not mutually exclusive. Adding both is a reasonable setup, and the reason to is
the token, not the tool count: a suite server that can send mail holds a credential that can send
mail, fo