Lets an AI assistant perform full Gmail mailbox triage including searching, labeling, archiving, snoozing, and unsubscribing.
Also known as csitte/mailwarden
- Stars
- 0
- Tools
- 21
- Downloads, 30 days
- —
- Latest version
- 0.31.2
- Last commit
- Nov 15, 2026
- License
- MIT
What is mailwarden MCP?
mailwarden lets an AI assistant perform full Gmail mailbox triage including searching, labeling, archiving, snoozing, and unsubscribing. It exposes 21 tools, such as search, get_thread, read_attachment.
Summary generated from the project's README
About mailwarden MCP server
Managing a Gmail inbox through an AI assistant is possible with mailwarden, a native MCP server designed for full mailbox triage. It allows users to search, label, archive, and unsubscribe from emails directly from their client. Unlike other implementations, it features mailbox-side snooze, which uses dated labels and a sweep process to make messages resurface in the inbox on a specific date. This ensures the snooze action is visible within the Gmail interface itself and survives server restarts.
Security is a primary focus, as the server includes no send tools by default to prevent prompt-injected mail exfiltration. Users can opt into a drafts tier to save messages for manual sending, but the server refuses to execute messages.send or permanent deletion commands unless specifically configured. The server also provides high-accuracy search by re-verifying Gmail index results against live labels to eliminate stale read-state errors. It is a local deployment that connects to the Gmail API and supports bulk operations of up to 1000 messages per request.
What you can do with it
- 1Snooze emails for laterAsk the assistant to archive a thread now and have it reappear in your inbox on a specific future date.
- 2Verify sender authenticityCheck if an email claiming to be from a bank is legitimate by inspecting the recorded SPF, DKIM, and DMARC results.
- 3Perform bulk inbox cleanupRequest the assistant to archive or label all messages that match a specific search query in large batches.
- 4Eliminate search inaccuraciesFind truly unread messages without being misled by stale search index results.
Written from the project's README. Every use case is checked against a quote from it.
How to install mailwarden MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall mailwarden MCP in Claude Code
$ claude mcp add mailwarden -- npx -y mailwardenInstall mailwarden MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mailwarden": {
"command": "npx",
"args": [
"-y",
"mailwarden"
]
}
}
}Install mailwarden MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mailwarden": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mailwarden"
]
}
}
}Install mailwarden MCP in VS Code CLI
$ code --add-mcp '{"name":"mailwarden","type":"stdio","command":"npx","args":["-y","mailwarden"]}'Install mailwarden MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mailwarden": {
"command": "npx",
"args": [
"-y",
"mailwarden"
]
}
}
}Install mailwarden MCP in Codex
$ codex mcp add mailwarden -- npx -y mailwardenInstall mailwarden MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mailwarden] command = "npx" args = ["-y", "mailwarden"]
Install mailwarden MCP in Gemini CLI
$ gemini mcp add -s user mailwarden npx -- -y mailwardenInstall mailwarden MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mailwarden": {
"command": "npx",
"args": [
"-y",
"mailwarden"
]
}
}
}mailwarden MCP tools 21
Detected from the READMEsearchget_threadread_attachmentlist_labelsget_profilewhat_changedfollow_upslist_unsubscribecreate_labelmodify_labelsundo_bulk_modifydownload_attachment
| search | — | |
| get_thread | — | |
| read_attachment | — | |
| list_labels | — | |
| get_profile | — | |
| what_changed | — | |
| follow_ups | — | |
| list_unsubscribe | — | |
| create_label | — | |
| modify_labels | — | |
| undo_bulk_modify | — | |
| download_attachment | — |
Show all 21 toolsShow fewer tools
export_threadlist_filterspreview_filtercreate_filterdelete_filtercreate_draftupdate_draftbulk_modifymailto
| export_thread | — | |
| list_filters | — | |
| preview_filter | — | |
| create_filter | — | |
| delete_filter | — | |
| create_draft | — | |
| update_draft | — | |
| bulk_modify | — | |
| mailto | — |
Configuration
MAILWARDEN_ACCOUNTMAILWARDEN_AUTO_SWEEPSet to 1 to sweep due snoozes at startup and hourly while running
MAILWARDEN_CREDENTIALSPath to the Google OAuth credentials.json (Desktop app client)
MAILWARDEN_DIRConfig directory (default ~/.mailwarden), holds credentials.json and token.json
MAILWARDEN_DOWNLOAD_DIRRestrict download_attachment and export_thread writes to this directory (recommended for HTTP hosting)
MAILWARDEN_TOKENMAILWARDEN_TOOLS
| Name | Description | |
|---|---|---|
| MAILWARDEN_ACCOUNT | — | |
| MAILWARDEN_AUTO_SWEEP | Set to 1 to sweep due snoozes at startup and hourly while running | |
| MAILWARDEN_CREDENTIALS | Path to the Google OAuth credentials.json (Desktop app client) | |
| MAILWARDEN_DIR | Config directory (default ~/.mailwarden), holds credentials.json and token.json | |
| MAILWARDEN_DOWNLOAD_DIR | Restrict download_attachment and export_thread writes to this directory (recommended for HTTP hosting) | |
| MAILWARDEN_TOKEN | — | |
| MAILWARDEN_TOOLS | — |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubmailwarden
A reliable, native Gmail MCP 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 answeris:unreadfrom 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, sosearchre-verifies every hit against its live labels. Paginated viapageToken/nextPageToken. (the measurements) - Sender authentication, not sender spelling.
get_threadreports 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 Gmail's own report only — the one written under the idmx.google.com; a message can carry forged ones of its own — says whether a passing DKIM signature belongs to theFromdomain, and saysuncheckedwhen nobody checked, because a missing check is not a passing one. - Bulk operations that scale.
bulk_modifyarchives/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
outputSchemaand returns validatedstructuredContentalongside fenced JSON text — no parsing guesswork for clients. Failures are structured as well: acodeand aretryableflag, 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,drafts.send, permanent deletion and forwarding settings, whatever a compromised or careless caller asks for — and every other draft endpoint too, unless you switch on the opt-indraftstier, which saves drafts for you to send yourself. 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 aread-tier deployment makes no outbound request at all. Details under Security & privacy and Unsubscribing. - Correct with real-world mail. RFC 2047 headers decoded (
=?UTF-8?B?…?=→ readable text), bodies decoded by their bytes and their declared charset (text Gmail already converted to UTF-8 is read as UTF-8 whatever the header says, anything else in the charset it names; 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. Two capabilities are still unique to mailwarden as far as we have looked (mailbox-side snooze, search re-verification), and one deliberate omission is a security feature, not a gap. A third, sender authentication, was unique when it shipped and no longer is: @agentcomms/gmail-mcp has read Authentication-Results since 18 September 2026, trusting only the report whose authserv-id is mx.google.com. It has its own column below since 13 October 2026. Google's own server is also narrower than it looks: draft-only, and no trash, filters or unsubscribe.
| Capability | mailwarden | Google official | taylorwilsdon | a-bonus | aaronsb | klodr | agentcomms | gmail-tidy |
|---|---|---|---|---|---|---|---|---|
| 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 | ✅ Gmail's own report only, values token-validated, DKIM alignment | — | — | — | — | — | ✅ Gmail's own report only, DKIM alignment | ⚠️ fail values from the first header, issuer unchecked |
| Sweep / bulk over a query — one action across every thread a search returns | ✅ 1000/req, partial-success | — | ⚠️ batch by explicit ids; filter apply relabels over a query, no re-check |
— | ✅ previewed query, up to 10,000, no re-check | ⚠️ batch by explicit ids | ⚠️ batch by explicit ids, exact per-message undo | ⚠️ over a query, capped at 5,000, no preview or re-check |
| Unsubscribe — per-sender overview + RFC 8058 one-click opt-out, no send scope needed | ✅ | — | ⚠️ header shown, no action | — | — | — | — | ⚠️ link shown, no action |
| Inbox triage overview — one call that buckets what is waiting | ✅ sender/label/age + header signals | — | — | ✅ heuristic flags + stats | ⚠️ unread list, no buckets | — | — | ⚠️ sender stats + newsletter list, no buckets |
| Server-side filters — rules that keep triaging with no assistant in the loop | ✅ never forwarding | — | ✅ | — | ✅ previewed; ⚠️ forwarding allowed unless draft-only policy | ✅ never forwarding | — | ✅ never forwarding or trash |
| No send tools — by design — a prompt-injected mail has no exfiltration path | ✅ no compose by default; ⚠️ opt-in draft-only tier | ⚠️ draft-only | ❌ sends | ❌ sends | ❌ sends; ⚠️ opt-in draft-only policy | ❌ sends | ❌ sends; ⚠️ per-message approval, in chat by default | ⚠️ draft-only |
| Least-privilege tool tiers — OAuth scopes derived from the tools you enable | ✅ | ⚠️ scope split | ⚠️ --permissions narrows scopes per service (cumulative or +-union); tiers narrow tools only |
— | ⚠️ per-account read/readwrite, at call time | ⚠️ inverse: tools gated by granted scopes | ⚠️ tier per mailbox picks the scopes; writes checked against the grant at call time | — |
| Token encryption at rest | ✅ AES-256-GCM by default, key in the OS keystore; a passphrase where there is none | n/a (hosted) | ⚠️ file mode 0600; bucket CMEK on GCS |
— | — | — | ✅ OS keychain by default; owner-only file by choice | ✅ AES-256-GCM by default, key in the OS keystore |
| No vendor cloud — you operate the server | ✅ | ❌ Google-hosted | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
Structured outputs — every tool declares an outputSchema |
✅ | ✅ documented per tool in its reference | — | — | — | ⚠️ two tools (download_email, download_all_attachments), more planned |
✅ every tool | — |
Snapshot as of 13 October 2026 — the oldest of the seven column checks (Google's reference, last read that day), and so the only date the table as a whole can claim. Each repository column is brought forward by reading the diff against the revision recorded in docs/comparison-sources.json whenever npm run table-sources reports a move. On 25 October 2026 four of them moved at once. aaronsb went to 9c9f8033 (v4.8.0), and two of its cells with it: since 16 October 2026 it applies a label change to everything a query matches, behind a preview that counts the set, keeps the ids on the server and hands back a token valid once for thirty minutes (up to 10,000 messages; the matches are not re-checked), and it creates, updates and deletes filters behind the same kind of preview — forwarding included unless its draft-only policy is set. taylorwilsdon went to fcbf5a2c (v2.2.0); --permissions now also takes a union such as gmail:readonly+send that grants only the named levels, which the least-privilege cell now names. klodr went to e5c080c3 (3.0.0); create_filter now refuses a forwarding action whatever the scopes, and its filter cell says so. agentcomms went to 261cae4f (0.28.0, with per-recipient rules on what it sends); no cell moves. On 8 November 2026 all six repository columns had moved again — taylorwilsdon to aa91bf75, a-bonus to 22856e1f, aaronsb to 5bf9ef73, klodr to ed1e7785, agentcomms to 42efa4c8, gmail-tidy to 00921c8f — and each diff was read with their draft tools in view; no cell moves. Google's tool reference, last read on 13 October 2026, documents an output schema on every one of its eleven tools; it is still Developer Preview, with no send, trash, filter, snooze, unsubscribe or query-driven tool. — = not offered / not documented. Columns are the servers a reader is most likely to reach for — Google's first-party one, plus the three largest community servers still under maintenance — and klodr, which comes closest to mailwarden's own least-privilege design. agentcomms (@agentcomms/gmail-mcp, read at 01cee751 on 13 October 2026) was added the same day for two reasons: it is the only other server we know of that reads Authentication-Results, and it pins that read to Gmail's own report, which is stricter than what mailwarden did until then and the reason mailwarden now does the same; and its npm reach overtook klodr's within a month of its first release. Its bulk path is per id, not per query, but every change returns an exact per-message undo — the design mailwarden's bulk_modify adopted as undo: true. It sends, behind a per-message approval whose default is a yes in the conversation; its own README says the software cannot tell that yes from the agent's, and offers a terminal confirmation (confirm) or no sending at all (never) instead. gmail-tidy (gmail-tidy-mcp, read at 6df48c69 on 25 October 2026) was added that day because its stated position is the closest to this one: no send tool and no trash, a build test that fails on either, and filters that can neither forward nor trash. It does write drafts, which puts it on the send row next to Google's server rather than next to this one — its own README says plainly that its token could send. It was ahead of mailwarden on one row, and mailwarden has since taken the same design over: it encrypts the token by default, with the key in the OS keystore. Its bulk runs over a query, capped at 5,000 messages, with neither a preview nor a re-check, and it reads SPF/DKIM/DMARC failures from the first Authentication-Results header without asking which server wrote it. Its npm reach matched mailwarden's within ten days of its first release. aaronsb was added on 8 September 2026, and the reason it was missing is worth stating plainly: the selection had been made by capability overlap, so a server an order of magnitude larger than the smallest column sat outside the table while that column stayed in it. It earns its place on the send row rather than on size. It was the first server here besides mailwarden that can be made to refuse sending at all — GWS_SAFETY_POLICY=draft-only-email blocks send, reply, replyAll and forward; agentcomms has since joined it with a never send policy — and the difference that keeps the row honest is where the promise lives: there, sending is the default and the refusal is an operator's environment variable; here, no tool to send was ever written. Its no-delete policy stands in the same relation to this project's trash-only rule. The filter row asks the same question from the other end, and a third project shows why it is one: c0webster/hardened-google-workspace-mcp, a fork of the taylorwilsdon column made for no reason but this one, removes create_gmail_filter and delete_gmail_filter outright because a filter can forward — which is exactly the risk, answered by dropping the capability. mailwarden keeps the capability and removes the risk instead: create_filter has no way to express a forward, and list_filters surfaces the ones that already exist so they can be audited. That fork also shows where a promise of this kind usually leaks, which is why the row above is about the tool surface and the egress guard rather than about scopes: it drops gmail.send but keeps gmail.compose — commented "for draft creation/editing only (NOT sending)" — and gmail.modify. Google documents the first as "Manage drafts and send emails" and the second as "Read, compose, and send emails", so the promise does not rest on one scope too many but on two, and gmail.modify alone would be enough — the same scope this project holds in its own manage tier, which is exactly why the row points at the tool surface. Its token can send; only its tool list cannot. The most installed Gmail server is absent for that reason and not by oversight: GongRzhe/Gmail-MCP-Server is archived, its last commit dating to August 2025, and it still drew 112,163 npm downloads in the month to 29 August 2026. Reach and currency are different questions, and a comparison of what a server does today can only answer the second. Send capability is listed as a security property: mailwarden's lack of it is intentional (see Security & privacy). The encryption row asks who holds the key: mailwarden keeps a random key in the OS keystore by default, as gmail-tidy does, and falls back to a passphrase you set where no keystore is reachable — and to a plaintext file where you set none, which is why the cell names both; 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 and gmail-tidy (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.
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; by default and with the key in the OS keystore, agentcomms and gmail-tidy, whose design mailwarden has since taken over), scope-driven tool gating (klodr inversely; taylorwilsdon in our direction, and further than this row said until it was corrected — besides --read-only, which switches the OAuth flow to the read-only scope map, he has had per-service permission levels since 25 February 2026: --permissions gmail:organize builds the requested set from cumulative levels — readonly, organize, drafts, send, full — and his tool registry then disables every tool whose declared scopes fall outside them, deliberately skipping scope-hierarchy expansion so that organize really does exclude gmail.send. What separates that from this row's claim is the direction, not the strength: the level is picked per service rather than derived from the tools you enable, so --tool-tier core --tools gmail still asks for the full Gmail scopes unless a level is named, and neither mode has a guard at the request itself. Our August round read only the tier path and understated him here from 26 August on; re-read in his auth/permissions.py, auth/scopes.py and core/tool_registry.py at 54b1c56 on 7 September 2026 — the day we read, at the revision his repository stood at. The tier half was checked on 26 August 2026 and corrected 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 — taylorwilsdon's filter apply, aaronsb's previewed modifyMatching and gmail-tidy's organize_emails now do the first half, all over messages.list, and none of them the second.
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, for every mailbox it is pointed at. Giving Gmail to mailwarden instead means the mail half of
your setup has no compose, reply, forward or send tool at all — or, with the opt-in drafts tier,
tools that save drafts and none that send them. Where that promise rests differs by
tier, and the distinction matters: on read Google enforces it at the token (gmail.readonly,
which the send endpoints reject), while on manage it rests on the tool surface — Gmail does
accept gmail.modify for sending, so the scope alone is no guarantee. In both cases the egress
guard refuses messages.send and drafts.send in the server itself, and every
other draft endpoint unless the drafts tier is on, so an injected message in your inbox has no
tool to reach for and no endpoint to reach.
Practical shape: point the suite server at the services you want and disable its Gmail tools
(--disabled-tools, or a tier that omits them), and run mailwarden alongside for mail. Keep the
tier rule in mind — at most one mailbox per client config should carry
writing tiers.
mailwarden MCP questions
How do I add mailwarden MCP to Claude Code?
Run claude mcp add mailwarden -- npx -y mailwarden in your terminal. Add --scope user to make it available in every project.
How do I add mailwarden MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does mailwarden MCP provide?
It exposes 21 tools, including search, get_thread, read_attachment, list_labels, get_profile.
Does this server support snoozing emails?
Yes, it features mailbox-side snooze which archives a thread and makes it resurface in the inbox on a specified date.
Is the search feature accurate regarding unread messages?
Yes, the search tool re-verifies every hit against live labels to prevent the stale read-state drift common in Gmail's index.
How does it handle sender authentication?
It reports SPF/DKIM/DMARC results recorded by Gmail's own receiving server to verify if a sender is legitimate.