Log inSubmit server
Mailwarden logo

Mailwarden

by csitte

Native Gmail MCP server for live mailbox search, triage, labels, filters, attachments, unsubscribe actions, and date-based snoozing.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

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"
      ]
    }
  }
}

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

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 AI clients directly to the Gmail API for mailbox search, reading, triage, labeling, filtering, attachment downloads, and message-state changes. Its search rechecks read state and other label predicates against live thread data, while snooze archives threads and restores them through dated labels and a sweep. The server also exposes Gmail event history, sender authentication results, newsletter opt-out handling, and structured triage summaries. Reach for it when an agent needs current mailbox state and controlled write operations without send or forwarding tools.

Use cases

  • Search live Gmail threads by sender, date, label, or read state
  • Triage an inbox with sender, age, label, and message-signal summaries
  • Bulk-archive, label, or mark messages after previewing a query
  • Snooze threads until a date and resurface them with a scheduled sweep
  • Review newsletters and perform RFC 8058 one-click unsubscribes

Key features

  • Live Gmail API access with search-result label rechecking
  • Mailbox-side date and time snoozing
  • Bulk label changes with dry runs and optional verification
  • Gmail filter creation, auditing, and deletion
  • SPF, DKIM, and DMARC result reporting
  • No send, forwarding, or permanent-deletion tools

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 Today

Recent health check succeeded.

8/8 checks healthy over the last 79d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 8d 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 commitTodayMost 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 MCP. It works against the live Gmail API rather than a synchronized mailbox index, so agents can search, inspect, classify, and modify messages from the connected account. Search results are checked against live labels for predicates such as read state, inbox membership, starred status, and categories.

The distinctive workflow is mailbox-side snoozing. A snoozed thread leaves the inbox and receives a dated label; a later sweep returns due threads to the inbox as unread. The state is visible in Gmail and survives server restarts. The server also intentionally omits send, draft, forwarding, and permanent-deletion paths. Unsubscribe operations are the exception: they can contact an HTTPS one-click endpoint advertised by a message.

How it works

Install the package with npx -y mailwarden and connect it to an MCP client. Gmail authorization supplies access to the selected mailbox. Calls are made against Gmail as needed, and the server does not retain a synchronized mailbox snapshot between calls.

Search uses Gmail query syntax and returns paginated thread summaries. A short page may still have more results, so callers should continue while nextPageToken is present. Gmail excludes spam and trash unless the query explicitly includes them. For incremental monitoring, what_changed accepts a previously returned history ID and returns mailbox events plus the next ID; Gmail history is retained for roughly a week.

Bulk changes are submitted in batches and report partial failures. verify reads labels back to observe the result, while dryRun previews a bulk operation without changing messages. crossCheck compares two Gmail query paths before writing, but agreement does not prove that the underlying index is current.

Setup and configuration

Run the package through the npm executable:

Terminal
npx -y mailwarden

Authorize Gmail for the account the MCP client should use. If an earlier authorization lacks the scope required by filter management, run mailwarden --auth again. Filter listing and creation require the gmail.settings.basic scope.

Attachment downloads can be restricted to a local directory with MAILWARDEN_DOWNLOAD_DIR. When set, requested destination paths are resolved inside that directory and existing files are never overwritten. Optional token encryption is available with MAILWARDEN_TOKEN_PASSPHRASE.

Tools and capabilities

  • Search Gmail with native query syntax, pagination, live label rechecking, and derived signals for newsletters, automation, calendars, and reply-to mismatches.
  • Read thread headers, plaintext and HTML bodies, attachment metadata, and receiving-server SPF, DKIM, and DMARC results.
  • List labels, snoozed threads, filters, subscriptions, unsubscribe options, and the authorized account profile.
  • Produce triage summaries grouped by sender, label, age, unread state, attachments, and message-header signals.
  • Add or remove labels on one thread or across a query; archive, mark read or unread, trash, restore, and create labels.
  • Create and delete Gmail filters with label-based actions, including optional application to existing messages.
  • Snooze and unsnooze threads, then sweep due snoozes back into the inbox.
  • Download attachments to local paths and perform RFC 8058 one-click unsubscribe actions, singly or in bulk.
  • Track mailbox changes using Gmail history IDs and structured event responses.

Limitations and notes

get_thread takes a thread ID, not a message ID. Its full mode is needed for bodies and attachment metadata; metadata-only mode omits those fields rather than returning empty values. Authentication results describe what Gmail's receiving server reported and should be interpreted with DMARC alignment and the reporting server identity in mind.

Bulk operations can be capped by maxMessages, and submitted counts do not necessarily prove that Gmail changed every targeted message unless verification is requested. Applying a filter to existing mail uses Gmail's search index and has the same index-staleness considerations as bulk modification.

Unsubscribe actions are irreversible from the server's perspective and confirm the address is active to the sender. Only HTTPS one-click endpoints from the message's own header are contacted; ordinary links are returned for a person to open, and mailto options are not used. A read-tier deployment makes no outbound request.

Snooze is implemented with labels and a sweep rather than a native Gmail snooze API. Due threads resurface when sweep_snoozed runs. Trash recovery is available for about 30 days through Gmail, and restoring a trashed thread does not automatically add it back to the inbox.

Read the full README View source on GitHub

Reviews

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

Frequently Asked Questions about Mailwarden

csitte/mailwarden is an MCP server that connects AI clients to Gmail through the live Gmail API. Its main tools search and read threads, manage labels, archive or trash mail, download attachments, create filters, track mailbox changes, unsubscribe from supported lists, and snooze threads until a date.

Install it with `npx -y mailwarden`, then authorize the Gmail account used by your MCP client. If filter tools need additional authorization, run `mailwarden --auth` again to obtain the `gmail.settings.basic` scope.

Yes. The `snooze` tool archives a thread and applies a dated snooze label, while `sweep_snoozed` returns due threads to the inbox as unread. It accepts dates, times, and presets such as tomorrow, next week, or in a number of hours.

No. It provides no send, compose, draft, or forwarding tools. The exception is unsubscribe handling, which can make an HTTPS request to an RFC 8058 one-click endpoint taken from a message's own List-Unsubscribe header.

The `search` tool checks returned threads against live labels for predicates including read state, inbox membership, starred status, and categories. This filters false positives caused by stale thread-level search data, although Gmail still excludes spam and trash unless the query names them.

Related MCP servers

All in Communication All alternatives
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>