Mailwarden logo

Mailwarden

by csitte

Native Gmail MCP server for live mailbox search, triage, labeling, snooze, attachments, filters, and unsubscribe actions.

Install Mailwarden

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "csitte-mailwarden": {
      "command": "npx",
      "args": [
        "-y",
        "mailwarden"
      ],
      "env": {
        "MAILWARDEN_DOWNLOAD_DIR": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— the server itself is confirmed live (we called its tools/list endpoint). The stdio install command is a separate, ongoing check.

Overview

csitte/mailwarden connects MCP clients directly to the live Gmail API for mailbox search, reading, triage, label changes, filters, attachments, and unsubscribe workflows. Its search operation rechecks several predicates against live labels, while get_thread exposes message bodies, attachments, and receiving-server SPF, DKIM, and DMARC results. Mailbox-side snooze archives threads and later restores them through a sweep, making it suitable for date-based inbox workflows. Reach for it when an agent needs Gmail write operations without a cached mailbox index or send-mail tools.

Use cases

  • Search Gmail threads with native query operators
  • Triage newsletters and automated messages by sender and signal
  • Snooze inbox threads until a date or time
  • Bulk-label or archive messages with verification
  • Review and unsubscribe from mailing lists

Key features

  • Live Gmail API access with search-result label reverification
  • Mailbox-side snooze with dated labels and due sweeps
  • Thread bodies, attachments, and SPF/DKIM/DMARC reports
  • Bulk label operations with dry-run and verification modes
  • RFC 8058 one-click unsubscribe support
  • Gmail filter creation and management without forwarding actions

Tools26

What Mailwarden lets your agent do. Expand a tool for its parameters.

Verified live~7.1k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 3d ago

Recent health check succeeded.

10/10 checks healthy over the last 89d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 2d ago via OSV.dev · mailwarden (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

npm downloads1.9kPackage downloads in the last 30 days.
Last commit3d agoMost recent push to the default branch.
Tools exposed26Callable tools this server registers over MCP.
Directory activity5 viewsConfig copies, upvotes, and views on AllMCPs.

How Mailwarden works

What csitte/mailwarden does

csitte/mailwarden exposes Gmail mailbox operations through the Model Context Protocol. It can search with Gmail's native query syntax, fetch thread content, inspect labels and filters, apply individual or bulk label changes, archive, mark read or unread, trash and restore threads, save attachments, and manage newsletter opt-outs.

Its distinctive workflow is mailbox-side snooze. Snoozing removes a thread from the inbox and applies a dated label; a later sweep returns due threads to the inbox as unread. The dates can be explicit or expressed with presets such as tomorrow, next week, a weekday, or a relative number of hours or days.

The server also provides triage-oriented views rather than only raw messages. A digest groups a mailbox slice by sender, label, age, unread state, attachments, and header-derived signals. Subscription listings group senders with their advertised unsubscribe options, helping an agent identify newsletter cleanup targets.

How it works

Calls go to Gmail's live API rather than a synchronized local mailbox snapshot. Search uses Gmail's query syntax and paginates with pageToken and nextPageToken. Because some Gmail index predicates can lag behind message labels, search rechecks supported read, inbox, starred, and category conditions against each returned thread. A short page can still have another page; the absence of nextPageToken indicates exhaustion.

get_thread accepts thread IDs, not message IDs. Full retrieval includes headers, plaintext and HTML bodies, and attachment metadata. Each message includes the receiving server's authentication report, including SPF, DKIM, and DMARC information. The reported authservId identifies whose result is trusted; an unchecked result means no report was available, not that the message passed.

Incremental mailbox monitoring uses Gmail history IDs. what_changed reports events since a previously held ID and returns another ID for the next call. History is retained for roughly a week, and the operation reports changes rather than reconstructing current state.

Setup and configuration

Install and run the package with:

Terminal
npx -y mailwarden

Authenticate the Gmail account with:

bash
mailwarden --auth

The authorized profile can be checked with get_profile, which returns the connected address and message and thread counts. Filter administration requires the gmail.settings.basic scope; rerun the authorization command if an earlier authorization did not include it.

Set MAILWARDEN_DOWNLOAD_DIR to restrict attachment destinations to a specific directory. download_attachment never overwrites an existing file and adds a numeric suffix when necessary.

Tools and capabilities

  • Search, read, paginate, and inspect Gmail threads without marking them read.
  • List labels, snoozed threads, filters, account details, and mailbox history changes.
  • Create labels, modify individual threads, and apply bulk label changes with optional dry runs, verification, or cross-checking.
  • Archive, trash, restore, mark read or unread, snooze, unsnooze, and sweep due snoozes.
  • Download attachments to a local path and inspect advertised unsubscribe methods.
  • Perform RFC 8058 one-click unsubscribe requests, including sequential bulk unsubscribe with sender deduplication.
  • Create and delete non-forwarding Gmail filters, optionally applying their actions to existing messages.

Bulk operations report counts, partial failures, and caps. Verification reads labels back to distinguish observed changes from IDs merely submitted to Gmail. Dry-run modes avoid mailbox changes, but query resolution can still reflect Gmail's search index.

Limitations and notes

The server intentionally has no ordinary send-mail path. Unsubscribe operations are the exception: they may contact an HTTPS endpoint taken from the message's own List-Unsubscribe header, and that request cannot be undone. Plain unsubscribe links are returned for a person to open; mailto options are not sent.

Spam and Trash are excluded from ordinary Gmail searches unless the query explicitly includes them. When expected mail is absent, a query with in:spam can distinguish a missing result from mail held in Spam.

bulk_modify acts on Gmail's message search index and can be capped by maxMessages. Its submitted count is not proof that messages changed; use verify when an observed outcome matters. what_changed cannot answer a first-look query and should not replace search or get_thread when current content is needed.

Snooze resurfacing depends on sweep_snoozed being run. Due threads remain labeled if a batch fails, allowing a later sweep to retry them. Trash recovery does not restore the INBOX label automatically, and Gmail permanently removes trashed mail after its retention period.

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Mailwarden

bulk_modify applies label changes to messages matching a Gmail query and reports counts, caps, and per-chunk failures. Use dryRun to preview the operation, verify to read labels back afterward, and crossCheck to compare query routes before writing. Search-index results can still require caution for exact read-state decisions.

Related MCP servers

Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMailwarden AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/csitte-mailwarden?style=directory)](https://allmcps.com/mcp/csitte-mailwarden)
HTML Embed
<a href="https://allmcps.com/mcp/csitte-mailwarden"><img src="https://allmcps.com/api/badge/csitte-mailwarden?style=directory" alt="Mailwarden on AllMCPs" /></a>