Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
npx -y [email protected]Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
MAILWARDEN_DIR=<value> MAILWARDEN_CREDENTIALS=<value> MAILWARDEN_AUTO_SWEEP=<value> MAILWARDEN_DOWNLOAD_DIR=<value> claude mcp add io.github.csitte-mailwarden -- npx -y mailwarden@0.31.2รันในเทอร์มินัล
{ "mcpServers": { "io.github.csitte-mailwarden": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "MAILWARDEN_DIR": "<value>", "MAILWARDEN_CREDENTIALS": "<value>", "MAILWARDEN_AUTO_SWEEP": "<value>", "MAILWARDEN_DOWNLOAD_DIR": "<value>" } } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดA reliable, native Gmail MCP server — full mailbox triage for AI assistants, with the feature no other Gmail MCP server ships: mailbox-side snooze.
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)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 Gmail's own report only — the one
written under the id mx.google.com; a message can carry forged ones of its own — says whether a passing
DKIM signature belongs to the From domain, and says unchecked when nobody checked, because a
missing check is not a passing one.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.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.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 and
Unsubscribing.=?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.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.
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.
Snapshot as of 13 October 2026 — the oldest of the seven column checks (Google's reference and a-bonus, both 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. a-bonus has not moved since 13 October 2026. 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.
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. 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 every draft endpoint in the server itself,
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.
Ask an assistant to "archive the unread promotional mail that's already skipped my inbox" and it will reach for the obvious query, category:updates is:unread -in:inbox. A server that trusts Gmail's index now archives threads you had already read — mail you never meant to touch, gone in a bulk action you can't easily reverse.
Measured, not asserted. In one real mailbox (~70,000 messages), category:updates is:unread returned 131 threads through threads.list, and only 17 of them held an unread message — 87% stale. The same query, same mailbox, same minute, asked through messages.list instead: 19 messages, none stale. So this is not "Gmail search is unreliable" — the thread view of read state lags while the per-message view does not, and search goes through threads.list. A second mailbox, measured identically on the same day, drifted not at all.
Method, all three queries, the controls, and what the finding is not (it is not the index dropping the predicate, and not a quirk of exotic operator combinations): Gmail's thread index can answer is:unread from a stale read state — a standalone report, every figure traced to a recorded measurement.
Which is the whole point: a server cannot know which kind of mailbox it is in. Re-verification costs nothing where nothing drifts, and saves you where it does — in the measurement above, every thread search dropped was genuinely read, and it discarded no genuinely unread mail.
Where it is not free: the bulk tools. search re-verifies because it fetches every hit anyway; bulk_modify (and create_filter's applyToExisting sweep) is sized in thousands of messages, where one fetch per hit is a different order of cost. Both act on what the index returns — and bulk_modify reports unverifiedPredicates, the conditions from your query that were taken on the index's word (+UNREAD, -INBOX, …). Empty means there was nothing to distrust. Non-empty and the result has to be read-state-precise? Resolve the set with search first and act on those thread ids. A dryRun does not close this gap: it re-reads the same index, so it confirms how big the set is, never whether it is right. What its previewToken does close is the other gap, between showing a set and changing one: without it, the write runs the query again and changes whatever matches by then.
The filter sweep does not report that field, deliberately. Its query is not yours — create_filter builds one from the criteria, parenthesising a query criterion and double-quoting every from/to/subject value, and both of those switch the predicate derivation off. The list would come back empty for every filter you can define, and an empty list here would read as "nothing to distrust" when it means "could not tell". So the caveat stays in prose, where it holds without exception: treat a sweep as acting on the index's answer, whatever it matched. Use verify: true to learn what the sweep actually changed, and search when the set has to be right before anything is written.
A cheaper half-measure, honestly labelled. bulk_modify also takes crossCheck: true, which asks Gmail the same question a second way before writing: every derived predicate is re-run as a label filter (labelIds) rather than as a query operator, and any message the two routes disagree about is left untouched and reported. The cost is one extra list call per predicate — flat, independent of how many messages match — where re-verification costs one fetch per hit. What it buys is bounded and worth stating plainly: a disagreement is real evidence, agreement is none at all, because both routes read the same index and an index can be consistently wrong. So unverifiedPredicates still reports what it always did, cross-check or not, and only search re-checks against the mailbox itself. Whether the two routes ever diverge in practice is unmeasured — node scripts/probe-crosscheck.mjs measures exactly that in your own mailbox, read-only and ids only.
mailwarden fetches every hit live anyway, so search re-checks the unambiguous predicates (is:unread, is:read, in:inbox, category:…, with negation) against each thread's true labels and drops the index's false positives before any tool sees them. The bulk action then runs on exactly the set you asked for. This is the difference between acting on what Gmail indexed and acting on what's actually in the mailbox right now — and it's why snooze/sweep are safe to hand to an assistant: the sweep resurfaces only threads whose snooze is genuinely due, verified against live labels at run time.
See it yourself — no Gmail account needed. From a clone of the repo (the demo is a repo-only verification script, not part of the npm package):
git clone https://github.com/csitte/mailwarden && cd mailwarden
npm install && npm run build
node scripts/demo-reverify.mjs
There is a second script next to it, node scripts/probe-reverify.mjs, which measures the same thing in your mailbox instead of a fake one — read-only, metadata only (no subject, sender or body is fetched), printing counts and label names. It is how the numbers above were produced, and how you can check whether your mailbox drifts at all.
The demo drives the real search() against a fake Gmail API whose index is deliberately stale (returns a read thread for an is:unread query, exactly as Gmail does) and shows mailwarden dropping the false positive. It asserts the outcome, so it exits non-zero if the behavior ever regresses. The same case is locked by unit tests in test/gmail.test.ts ("drops index false positives via live-label re-verify").
A recurring check — what came in since I last looked — is the expensive shape for a live server: the
obvious way to answer it is to search the whole slice again and compare. what_changed (read tier)
answers it from Gmail's own event log instead. Hand it the historyId a previous call or get_profile
returned, and it comes back with what arrived, what left, and which labels went on or came off, plus the
next id to keep.
This is not a cache, and the distinction is the whole design. The only thing that persists between calls is one number, and it persists in the caller. mailwarden still stores nothing about the mailbox, keeps no mirror and no index, and every call remains live against the Gmail API — the same rule as everywhere else here.
Two properties worth knowing before relying on it. It reports events, not state: a message marked
unread and then read appears under both, and both are true — for how the mailbox looks now, ask
search. And Gmail keeps roughly a week of history, after which an id is refused; mailwarden turns that
refusal into an error rather than an empty result, because nothing changed and I can no longer tell
you what changed call for opposite reactions and only one of them is safe to act on.
authentication answers, and what it doesn'tEvery message from get_thread carries an authentication object: the SPF, DKIM and DMARC
results the receiving server recorded, plus the domains each check actually validated.
{
"spf": "pass", "mailedBy": "forwarder.example", // envelope sender SPF checked
"dkim": "pass", "signedBy": "routing.example", // domain whose key signed it
"dmarc": "pass", "headerFrom": "authority.example", // the From domain DMARC evaluated
"dkimAligned": false, // the signer is not the From domain
"authservId": "mx.google.com", // who asserts all of the above
"returnPath": "srs0=…=authority.example=…@forwarder.example"
}
Read dmarc first. It is the only one of the three that ties a passing check to the From
address a human sees. spf: "pass" on its own says an envelope sender was authorised to send —
something a lookalike domain gets in minutes.
The three domains do not have to match, and a mismatch is not a finding. The object above is a
real message from a public authority, forwarded through a custom domain on a mail-routing service
before it reached the mailbox. Every domain differs from the others, and the mail is genuine:
forwarding rewrites the envelope sender (mailedBy becomes the forwarder), the forwarder signs
with its own key (signedBy), and only headerFrom still names the original sender — which is
exactly why DMARC, not SPF, is the check that carries meaning here. Treat the domains as the
explanation of a result, not as a test of their own.
What a pass does not mean. That the mail really came from that domain — not that the domain deserves anything. A phisher holds perfect SPF, DKIM and DMARC on the lookalike domain he registered this morning; authentication tells you who sent it, and the answer can be "exactly who it claims to be, and that is the problem".
dkimAligned answers the question a signature raises. Anyone can sign mail with a key for a
domain they own, so dkim: "pass" alone says only that someone signed. dkimAligned says whether
that someone is the From domain, or a parent or child of it. For two sibling subdomains it says
nothing: news.bank.example and mail.bank.example are aligned, a.co.uk and b.co.uk are not,
and without a public-suffix list the two cases look the same — so the field is absent rather than
wrong. In the forwarded example above it is
false, and correctly so: the forwarder signed. It is absent when DKIM did not pass. As with the
domains, false is an explanation, not a verdict — dmarc remains the check to read first.
What unchecked: true means. The message carried no Authentication-Results header from
Gmail — nobody looked. It is not a failure, and it is not a pass. The header is written by a server that
receives a message, so anything that never arrived from outside — your own sent mail, for
instance — should be expected to have none.
Forged reports. A message can carry Authentication-Results headers of its own — an attacker
writes whatever he likes into the mail he sends. Only Gmail's own report is read: the topmost
one whose authserv-id is mx.google.com, the trust boundary RFC 8601 tells a reader to rely on.
A report under any other id is never read, however convincing it looks, and a message that has
none from Gmail is unchecked even if it carries a forged one under another id. The limit: mail that
reached the mailbox without passing Gmail's inbound mail server — fetched from another account over
POP, or inserted by an app — may carry no Gmail report at all, and a forged one that claims
mx.google.com is then indistinguishable from the real thing. Mail Gmail received itself always
carries its own report on top, so there a forgery is never read; otherReports counts every report
that was not read. (Through 0.22.1 the first report was read whatever its id — right wherever Gmail
had written one, and wrong exactly where it had not.) Values are validated as tokens rather than passed through, so a field that reads
like a verdict cannot carry a sentence. If two results for the same method disagree — a second DKIM
signature that failed — the disagreement shows up in alsoReported instead of being swallowed.
All tools declare an outputSchema and return structured content (validated, machine-readable)
alongside the same JSON as fenced text — clients never have to parse prose.
A failure is structured too: isError plus a fenced JSON body with a code
(not_authorized, needs_reauth, insufficient_scope, forbidden_operation, not_found,
rate_limited, upstream_unavailable, network_error, invalid_input, declined_by_user, internal_error) and a
retryable flag, alongside the sentence a human reads. So "wait and try again" versus "re-run
mailwarden --auth" is something a client can decide, not something it has to infer from wording
that may be reworded next release. (No structuredContent on errors: that is validated against the
tool's outputSchema, which describes a success.) A rate_limited failure also carries
retryAfterSeconds, because there the wait is the remedy. An insufficient_scope failure names
the gap rather than the possibilities — which scope is missing, what it covers, and what the saved
authorization grants instead — by reading the token's own scopes when it lands, and the server
prints the same line on stderr at startup. It explains the refusal rather than preventing it:
the call still goes to Google, and Google is what turns it down. That matters most with a passphrase-encrypted token: the tier gate
at registration cannot decrypt it, so the surface is advertised in full and the gap would otherwise
surface as a bare 403 mid-task. A token encrypted with a keystore key keeps its scopes readable and
is gated like a plaintext one.
Gmail bills each call against a per-user budget of 6,000 units per minute, and the units are not uniform — fetching a thread is the expensive part, in whatever format it is fetched:
mark_unread costs what mark_read does.
Two consequences worth knowing before you build on this. Parallel agents share one budget —
they reach Gmail through a single server process as a single user, so four of them reading threads
at once spend four times as fast. And bulk_modify is cheaper than looping from six threads
on: up to 500 matching messages it costs 55 units, the price of five and a half archive calls,
and it grows by the thousand messages, not by the thread. verify: true reverses that — reading
the labels back costs 40 per thread, more than the loop it replaced.
If you do exceed it, mailwarden fails the call with rate_limited and retryAfterSeconds: 60.
That failure is temporary and waiting genuinely fixes it — the budget is counted per minute.
mailwarden absorbs one such wait (about 20 seconds) itself before reporting; past that it hands the
decision back rather than holding your tool call open. That holds for the tools that fetch many
threads in one call too: search fails with rate_limited rather than returning a list the quota
cut short, and bulk_modify with verify and list_subscriptions stop fetching and report what
they did not reach as unverifiable and unknown (for bulk_modify the change is already made,
and failing would hide it). Note that Gmail reports this as a 403 as readily as a 429, so a
client keying on the status alone will mistake it for a permission problem — key on the code.
snooze removes INBOX and applies a dated label MCP/Snoozed/<key>, where the key is either YYYY-MM-DD (due all day) or YYYY-MM-DDTHHMM (due at that local minute). The until argument takes an explicit date, a date+time (2026-06-20 9am, …T17:00), or a preset resolved server-side — today, tomorrow, weekend (next Saturday), next week (next Monday), a weekday name (monday–sunday, next occurrence), in N days, or in N hours — and a date preset may carry a trailing time (tomorrow 9am, monday 8:30), so the caller never has to compute the moment itself. sweep_snoozed finds due labels and returns those threads to the inbox (marked unread); a timed snooze wakes at the first sweep on/after its minute, so wake latency equals your sweep interval. Run the sweep:
sweep_snoozed tool),mailwarden --sweep,MAILWARDEN_AUTO_SWEEP=1 (hourly sweep while the server runs).create_filter sets up a Gmail server-side rule: mail matching the criteria automatically gets the
given label actions — the mailbox keeps triaging itself with no assistant in the loop.
from, to, subject, query (full Gmail search syntax), negatedQuery,
hasAttachment, excludeChats, and size + sizeComparison (smaller/larger, given together).
At least one is required.addLabels / removeLabels, by name or id (an unknown name in
addLabels is auto-created, nested via /). Common recipes: skip the inbox → removeLabels: ["INBOX"];
auto-mark-read → removeLabels: ["UNREAD"]; auto-trash → addLabels: ["TRASH"];
star → addLabels: ["STARRED"]; never-spam → removeLabels: ["SPAM"]; file under a label → addLabels: ["Receipts"].applyToExisting: true to also apply the same actions once to mail already in the mailbox —
mailwarden builds a Gmail search from the criteria and runs a bulk modify (up to maxMessages,
default 1000; same unverified-index caveat as bulk_modify, and the one-off pass excludes Spam/Trash).
This requires at least one positive criterion (from/to/subject/query/hasAttachment:true/size):
an exclusion-only rule (negatedQuery or hasAttachment:false) is refused for applyToExisting
because it would match almost the whole mailbox — create such a filter without the flag.
The outcome comes back under applied (the query used, matchedMessages/submittedMessages/submittedThreadCount
counts, capped when the match set hit maxMessages, per-chunk failed, and an error string if the whole
pass failed); it's null when applyToExisting was not set. submittedMessages is what was handed to the API,
not what changed — pass verify: true alongside applyToExisting to read the labels back and get
applied.verified {applied, notApplied, unverifiable}, the same check as bulk_modify's verify
(one extra read per affected thread, so off by default). The filter is created first, so a partial or
failed backlog pass is reported in applied, never raised — the rule still stands.gmail.settings.basic scope; re-run --auth once if you authorized an older version.
Not available in read-only mode.list_unsubscribe (read tier) reports what the sender offers, without contacting anyone. It reads the
newest message that actually carries a List-Unsubscribe header — a reply threaded onto a newsletter
sits at the end and advertises nothing, which would otherwise read as "this list has no opt-out".
When a thread advertises no opt-out header at all, list_unsubscribe looks in the message body and
reports the unsubscribe links it finds there as bodyCandidates — plenty of senders put the link only
in the footer, and answering "no opt-out options" for them is true about the headers and wrong about
the mail. Those links are reported, never fetched, they cannot be handed to unsubscribe, and
hasUnsubscribe stays false for them, because that flag has always described the headers. The search
costs one full thread fetch and happens only in that case.
list_subscriptions (read tier) does the same across a whole slice, grouped by sender, so you can see
who keeps writing and which of them can actually be left — one header fetch per sender rather than
per thread. unsubscribe and bulk_unsubscribe (manage tier) act on it — and that is the only
place mailwarden ever talks to a host that isn't Google, so the rules are tight:
navbuildz/gmail-mcp-server, does fetch them, following redirects, when the
header is missing.List-Unsubscribe-Post.
A plain https: link is meant for a human in a browser and is handed back, not fetched.mailto: opt-outs are never performed. They would require sending mail, which mailwarden cannot
do. The address is reported so you can act on it yourself.List-Unsubscribe=One-Click and is
never derived from anything; the response body is cancelled unread. What returns to the model is the
status code and the URL actually called — no content from the endpoint, so it cannot answer with
instructions. (A 301/302/303 redirect is followed as a GET, i.e. with no body at all.)bulk_unsubscribe takes thread ids
(never a query — a query-driven bulk would fire off a request per matched sender before anyone had
looked). Threads from a sender whose request already went out are reported with duplicateOf and
cost no second request: two threads from one list share an opt-out, and calling it twice only
confirms your address twice. A sender is only recorded once a request actually reached an
endpoint, so a refusal or a dropped connection still leaves the next thread its own try — and if
the skipped thread advertises a different endpoint, the reason says so, since one sender can run
several lists. That memory spans calls for as long as the server runs, and unsubscribe shares
it: a call that times out is safe to repeat, and asking twice for the same newsletter contacts the
sender once. Pass force: true to unsubscribe for a deliberate second attempt — after an endpoint
answered 500, say. It is kept in memory only: persisting it would mean a second kind of local state
beside the token, which this server deliberately does not keep, so a restart forgets.
Capped at 25 threads and 60 seconds per call; whatever the budget doesn't cover comes
back as skippedOutOfTime rather than silently undone. None of it can be reversed, which is why all
three limits exist.::1 and 0:0:0:0:0:0:0:1 alike); an
address that does not parse is refused. DNS resolution and all hops share one 10-second budget. Not
rebinding-proof (fetch resolves again when it connects) — see SECURITY.md; what
survives that gap is a blind POST whose response is never read.Check it against your own mail before you trust it. From a repo clone (repo-only, not in the
npm package), after npm run build and mailwarden --auth:
node scripts/probe-unsubscribe.mjs --vet # category:promotions, 25 threads
node scripts/probe-unsubscribe.mjs "from:substack.com" --max 50 --vet
It prints each real List-Unsubscribe header next to what the parser made of it, and --vet also
runs the endpoint through the URL vetting and the address guard — so you see both whether the parser
understood the header and whether the guards would have let that opt-out through. Strictly
read-only: no request is ever made to a sender, and nothing in the mailbox changes.
What it can't undo: the request tells the sender your address is live. A sender that ignores its own
opt-out is beyond any client's reach — pair unsubscribe with create_filter or trash for those.
Not offering an automatable option is reported as unsubscribed:false with the alternatives, not as an
error. A read-only deployment gets list_unsubscribe and list_subscriptions, and never makes the
request at all.
A query that does not name a place never sees spam or trash. Gmail excludes both from any
search that does not say in:spam / in:trash, so from:someone returns nothing for a mail that
is sitting in the spam folder — and nothing in the answer says so. Measured against a live mailbox:
the same from: query returned 0 hits by default and 1 with spam included.
This matters because of why mail gets misfiled. A spam filter judges a message on its own; it cannot know that you signed up for something a minute ago, requested a password reset, or placed an order — so the confirmation you are waiting for is exactly the kind of mail that lands there. You know what you just did. The filter does not.
So when mail someone expects is missing, ask again with the place named:
search("in:spam newer_than:2d") # what got filed as spam recently
search("in:spam from:example.com") # the confirmation that never arrived
A thread returns to the inbox with modify_labels (remove SPAM, add INBOX), and a sender that
keeps being misjudged is best fixed for good with a never-spam rule — create_filter with
removeLabels: ["SPAM"] (see Filters).
Two things this server deliberately does not do. It does not scan the spam folder and judge what belongs there: measured over one real spam folder, 89% of it carries no mailing-list machinery at all, so "looks unlike bulk mail" flags nearly the whole folder and filters nothing. And it does not act on that judgement by itself — releasing mail from spam is a decision, and the context that makes it obvious ("I just registered there") lives in the conversation, not in the mailbox.
For the full threat model — trust boundary, per-threat mitigations, explicit non-goals, and how to report a vulnerability — see SECURITY.md. The highlights:
--http listener binds to 127.0.0.1
(not the LAN) and refuses to start without a MAILWARDEN_TOKEN bearer token — set
MAILWARDEN_ALLOW_NO_TOKEN=1 to override on a trusted, isolated network. On a loopback bind it
also validates the Host header (DNS-rebinding defense). For remote hosting, set MAILWARDEN_HOST
and front it with TLS.create_filter follows
the same rule: it can label, archive, trash, star or mark mail, but never creates a forwarding
filter (which would be an exfiltration path). list_filters still surfaces any forwarding filter
already on the account, so you can spot one. This holds because no such tool exists and none can be
registered at runtime; for the stronger variant, where Google refuses to send rather than
mailwarden declining to, see Read-only mode below. Read the promise as narrow, because it
is: it closes the route out through this server, not the assistant's other routes — a client
that can fetch a URL, write to a synced folder or run code still has everything an injected
message needs, and this server is what puts that message in front of it. See
non-goals.unsubscribe tool is the only code path that
contacts a non-Google host. Its endpoint is read from the message's List-Unsubscribe header —
never from a tool argument — the request body is fixed and the response body is discarded, so it
cannot become a data channel. https/default-port only, redirects re-validated, and any hop resolving
to a private, loopback, link-local or metadata address is refused. See
Unsubscribing.MAILWARDEN_TOOLS advertises only the tiers
you name — read (the read tools), manage (mailbox mutations, snooze, downloads), filters
(server-side filter CRUD, the only tier whose tools need gmail.settings.basic). Default is all
three; e.g. read,manage gives a full triage surface without filter management. The OAuth scopes
requested at --auth are derived from the enabled tiers — a read deployment asks only for
gmail.readonly, and gmail.settings.basic is requested only when the filters tier is on. And the
filter tools are hidden automatically when the stored token doesn't carry gmail.settings.basic
(e.g. a token authorized before you enabled the tier) — re-run --auth to grant it. Older tokens
without a recorded scope are advertised as before, with the runtime insufficient-scope message as the
fallback.MAILWARDEN_READONLY=1 (shorthand for MAILWARDEN_TOOLS=read) and only the
read tools (search, get_thread, read_attachment, list_labels, list_snoozed, get_profile, what_changed, triage_digest,
follow_ups, list_unsubscribe, list_subscriptions)
are registered — nothing that can change the mailbox or write
files is even advertised to clients (the filter tools, which need the broader gmail.settings.basic
scope, are excluded too). Recommended for shared/HTTP deployments that only triage.
It is also the only tier whose no-send property Google enforces: it holds a gmail.readonly
token, which Gmail's send endpoints reject outright. manage needs gmail.modify, and Gmail
does accept that scope for sending — mailwarden simply exposes no tool that would. So a read
deployment could not send even if this binary were replaced; a manage one cannot send because
there is nothing to call. (There is no send-free write scope to switch to — see
SECURITY.md, threat 1.)messages.send, drafts.*, messages.import/insert,
permanent deletion and every non-filter settings endpoint named in a deny list checked first, so
a later edit to the allowlist cannot reopen them by accident — including through the
/upload/gmail/v1/... route Google's client takes when a method is handed media. A request whose
host was rewritten (GOOGLE_CLOUD_UNIVERSE_DOMAIN, a rootUrl option) is refused before the token
leaves the process. Every method in Gmail's discovery document is tested against the guard. It
guards this server, not the
token: a stolen gmail.modify token can still send from elsewhere.MAILWARDEN_DOWNLOAD_DIR set, file writes — attachments and thread
exports — are confined to that directory (realpath-canonicalized, symlink-aware) and never
overwrite an existing file. Without it there is nothing to resolve the client-supplied path
against, so download_attachment and export_thread can write anywhere this process can — which matters for --http, where the client is remote.
Starting --http without the fence therefore prints a warning naming the exposure (it stays a
warning, not a refusal: unlike a missing bearer token this needs an authorized client, and
existing deployments depend on the current behaviour). A read-tier deployment is silent — it
never registers the tool.<untrusted-tool-output> markers
and stripped of invisible/BiDi-override characters, so clients can tell quoted mail content from
instructions. The strip also covers Unicode tag characters and the variation selectors supplement
(invisible ASCII smuggling), and it applies to structuredContent as well as the text copy — a
client reading the machine-readable half gets the same sanitized content.~/.mailwarden/.token.json holds a refresh token; on disk it is
protected only by mode 0o600 (a no-op on Windows). mailwarden --auth therefore stores it
AES-256-GCM-encrypted under a random key it keeps in the OS keystore — Windows Credential Manager,
the macOS Keychain, the Secret Service (GNOME Keyring, KWallet) on Linux — so a copy of the file
(a backup, a synced folder, another machine) is useless on its own. Where no keystore is reachable
(a Linux host without a desktop session, a platform without a prebuilt binding), set
MAILWARDEN_TOKEN_PASSPHRASE and the key is derived from that passphrase instead (scrypt); without
either, the token is stored in plaintext as before, and --auth and --check say so. A passphrase,
once set, takes precedence over the keystore. An existing plaintext token keeps working and is
encrypted at the next --auth — never rewritten behind your back. Note the boundary: this defends
against file theft, not against malware running as your user, which can ask the keystore for the
key, or read the passphrase from the environment, exactly as mailwarden does.claude mcp add mailwarden -- npx -y mailwarden
That's the whole install — npx fetches and runs the published package, no clone or build step. You only need Google OAuth credentials once (below).
First time setting up a Google OAuth app? Follow the step-by-step setup guide — it walks through the Google Cloud Console with exact click paths, explains the "unverified app" screen, and covers the trap that makes tokens die after 7 days. The short version:
credentials.json.credentials.json in ~/.mailwarden/ (or set MAILWARDEN_CREDENTIALS=/path/to/credentials.json).~/.mailwarden/token.json:
npx -y mailwarden --auth
Scopes requested: gmail.modify (read + label/archive/trash) and gmail.settings.basic
(filter management only). If you authorized a version before filters existed, re-run --auth
once to grant the added scope. To hold a token that Gmail itself refuses to send with, authorize
with MAILWARDEN_TOOLS=read — see Read-only mode above.npx -y mailwarden --check
It checks credentials.json, whether a token exists (and if it's encrypted), whether the
granted scopes cover your enabled tiers, and makes one live Gmail call to prove the token
still works — printing a concrete fix for anything that's wrong, and exiting non-zero if so
(handy in CI/health checks). Diagnoses the common traps: no/wrong credentials file, never
authorized, an encrypted token with no MAILWARDEN_TOKEN_PASSPHRASE or whose key is not in this machine's keystore, a missing scope, or the
7-day "Testing"-consent token expiry.Claude Code (local stdio):
claude mcp add mailwarden -- npx -y mailwarden
Claude Code plugin — the same server plus two skills: /mailwarden:setup walks you through the
OAuth setup and diagnoses a broken one, and /mailwarden:triage carries the operating rules an
assistant needs while working a mailbox — above all that search re-verifies and bulk_modify does
not, so a non-empty unverifiedPredicates means resolving the set with search before acting on it.
That rule protects the user only if the assistant follows it, and a tool description is read once per
call while a skill is read before the plan. The repo root is the plugin (.claude-plugin/plugin.json), so
from a clone:
claude --plugin-dir /path/to/mailwarden
It is submitted to Anthropic's community marketplace; once listed, /plugin marketplace add anthropics/claude-plugins-community
then /plugin install mailwarden@claude-community does the same without a clone. The plugin starts the
exact published version (npx -y mailwarden@<version>, bumped by the release script together with
server.json), because the directory reviews one revision and refuses a launcher that would run whatever
npm serves later. The plugin runs the full
tool surface — for a narrower tier (MAILWARDEN_TOOLS=read) or a second account, use claude mcp add with
the env you want instead (see Config and Multiple accounts).
That route gets the server without the skills: the npm package ships the server alone, and the skills
live in this repo's skills/ folder — to keep triage with a claude mcp add setup, copy
skills/triage from a clone into ~/.claude/skills/.
Claude Desktop — add to claude_desktop_config.json:
{
"mcpServers": {
"mailwarden": { "command": "npx", "args": ["-y", "mailwarden"] }
}
}
Or install the MCPB bundle (mailwarden-<version>.mcpb, attached to
GitHub releases from 0.10.0 on) as a Desktop extension — Settings →
Extensions → Install extension… — the same server, self-contained at run time (no npx; Claude
Desktop brings the Node runtime), with the tool tiers as a setting. The bundle is built from the packed
npm package (same file set as published; npm run mcpb, verified in CI: validated, unpacked and booted),
plus the OS-keystore binding for each platform it declares, pinned and hash-checked by the lockfile.
The one-time npx -y mailwarden --auth still applies
(Node needed once for that) — the bundle reads the same ~/.mailwarden/ token.
Smithery — listed in the directory as
csitte/mailwarden. Smithery shuts down its CLI,
toolbox, gateway and accounts on 31 October 2026 and stays on only as a public directory
(announcement), so there is no Smithery install path any more: install
with npx or the .mcpb above. Whether the listing itself stays after that date is up to Smithery.
Remote (Streamable HTTP) — for a VPS / claude.ai custom connector:
# Loopback + token required by default. For real hosting, bind outward and keep the token:
MAILWARDEN_TOKEN=<secret> MAILWARDEN_HOST=0.0.0.0 npx -y mailwarden --http # :8787/mcp
Then in claude.ai: Settings → Connectors → Add custom connector → your https://your-host/mcp URL. In Claude Code: claude mcp add --transport http mailwarden https://your-host/mcp.
One OAuth app (one credentials.json) can authorize several Gmail accounts. Each account keeps its
own refresh token in a separate file, selected by MAILWARDEN_ACCOUNT:
mailwarden --auth --account work # stores token.work.json
mailwarden --auth --account personal # stores token.personal.json
Run them side by side by registering the server once per account, each with its own
MAILWARDEN_ACCOUNT. Every instance carries its own token, its own granted scopes and its own tool
surface, and a tool call acts on the account of the entry that carries it and on no other:
{
"mcpServers": {
"gmail-work": { "command": "npx", "args": ["-y", "mailwarden"], "env": { "MAILWARDEN_ACCOUNT": "work" } },
"gmail-personal": { "command": "npx", "args": ["-y", "mailwarden"], "env": { "MAILWARDEN_ACCOUNT": "personal" } }
}
}
Account names are case-insensitive — they become filenames, so Work and work would be the
same file on Windows/macOS. mailwarden lower-cases them (--account Work → token.work.json) so a
name always maps to exactly one mailbox.
Which file --auth writes depends only on --account / MAILWARDEN_ACCOUNT — never on the
account you pick in the browser. Authorizing a second mailbox without --account would
therefore aim straight at the first one's token file, so --auth checks first and refuses
rather than replacing another mailbox's token; --force overrides it deliberately. The two knobs
are not interchangeable: MAILWARDEN_ACCOUNT is the one for several mailboxes out of one config
directory (it picks token.<name>.json), while MAILWARDEN_DIR moves the whole directory —
useful to keep setups apart entirely, but it does not give you a second account inside one.
npm run auth from a repo clone passes neither, i.e. it always serves the default account.
mailwarden --check shows the active account and lists the others it finds. With no
MAILWARDEN_ACCOUNT set, everything uses the default token.json exactly as before — this is fully
backward compatible.
Two entries are the easy case. Past that, two properties of this design start to matter.
Each instance brings its own tools. The tier split is 11 read + 16 manage + 4 filters, so a
full instance advertises 31 tools and four of them advertise 124. Clients that search their tool
surface on demand absorb that; clients that hold every definition in context do not.
Several accounts in one client share one model context. The account boundary binds a call to one mailbox — it does not stop text read from one mailbox from prompting a call against another, because all of those tool surfaces are in front of the same model. That is a limit of the boundary, not a defect in it; see threat 8 in SECURITY.md.
One move answers both: give exactly one mailbox write tools and leave the rest on read.
{
"mcpServers": {
"gmail-main": { "command": "npx", "args": ["-y", "mailwarden"], "env": { "MAILWARDEN_ACCOUNT": "main" } },
"gmail-work": { "command": "npx", "args": ["-y", "mailwarden"], "env": { "MAILWARDEN_ACCOUNT": "work", "MAILWARDEN_TOOLS": "read" } },
"gmail-club": { "command": "npx", "args": ["-y", "mailwarden"], "env": { "MAILWARDEN_ACCOUNT": "club", "MAILWARDEN_TOOLS": "read" } },
"gmail-archive":{ "command": "npx", "args": ["-y", "mailwarden"], "env": { "MAILWARDEN_ACCOUNT": "archive","MAILWARDEN_TOOLS": "read" } }
}
}
Three things follow at once: the read entries only ever ask for gmail.readonly, the one scope in
which no-send is enforced by Google rather than by mailwarden's tool surface; the four instances add
up to 64 tools rather than 124; and an instruction injected into any of them finds no write tool for
another mailbox to reach for. When one of the read-only mailboxes does need cleaning up, hand that
entry manage for as long as the work takes instead of permanently.
Separate clients — or separate sessions — remove the shared context entirely, at the price of never having two mailboxes in view at once. Worth it when several mailboxes genuinely need write tools; otherwise the tier split is the cheaper boundary.
No tool reads across mailboxes. search, triage_digest and list_subscriptions each serve
the one account their instance was configured with, so a question like "which newsletter writes to
all four" is four calls whose answers the caller combines. In a setup this size it is worth calling
get_profile before the first action that changes anything — it names the mailbox actually on the
other end.
git clone https://github.com/csitte/mailwarden && cd mailwarden
npm install && npm run build
node dist/index.js --auth
A clone deliberately arrives without a CLAUDE.md: the working instructions for this repository
are an internal document and are not tracked here. Nothing in the build, the tests or
npm run smoke needs them. The rules a contributor — or a coding agent — actually has to know are
in CONTRIBUTING.md (design rules
that are not up for grabs, the build/test loop) and SECURITY.md (the threat model
those rules come from).
Working and used in daily mailbox automation. Core Gmail tools + snooze implemented against @googleapis/gmail, covered by a vitest suite (1774 tests — npm run coverage). Current version: see the npm badge above, the changelog, or releases. PRs welcome — CONTRIBUTING.md covers the build/test loop and the design rules that are not up for grabs.
MIT © C.Sitte Softwaretechnik
Gmail MCP server for email triage: search, labels, archive, trash, unsubscribe, snooze.
{ "mcpServers": { "io.github.csitte-mailwarden": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "MAILWARDEN_DIR": "<value>", "MAILWARDEN_CREDENTIALS": "<value>", "MAILWARDEN_AUTO_SWEEP": "<value>", "MAILWARDEN_DOWNLOAD_DIR": "<value>" } } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ผู้เผยแพร่ระบุตัวแปรสภาพแวดล้อมเหล่านี้: MAILWARDEN_DIR, MAILWARDEN_CREDENTIALS, MAILWARDEN_AUTO_SWEEP, MAILWARDEN_DOWNLOAD_DIR
Mailwarden ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-17 Gmail MCP server for email triage: search, labels, archive, trash, unsubscribe, snooze.