Mailwarden

What the csitte/mailwarden MCP server does

The csitte/mailwarden MCP server exposes Gmail mailbox operations through the Model Context Protocol. It can find threads with Gmail query syntax, retrieve complete thread content, inspect labels and account details, and produce a structured triage digest with sender, label, age, unread, and attachment information.

Mailbox changes include archiving, marking threads read or unread, moving them to or restoring them from Trash, adding or removing labels, and applying label changes in bulk. Attachments can be written to a local path. The server also manages Gmail filters for automatic label actions on incoming mail, including optional application of those actions to existing messages.

Its 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. This state is visible in Gmail and survives server restarts.

How it works

The csitte/mailwarden MCP server sends requests to Gmail rather than maintaining a synchronized mailbox copy. Search accepts Gmail's native query syntax and returns paginated thread summaries. For predicates such as unread, read, starred, inbox, and category, returned threads are checked against live labels to reduce false positives from stale thread-level search state.

Use search to locate a thread, then pass its thread ID to get_thread for headers, plaintext and HTML bodies, and attachment metadata. bulk_modify operates on messages matching a Gmail query in batches of up to 1,000 API requests and reports partial failures. Its query uses Gmail's search index without the live re-verification performed by search, so precise read-state bulk actions should be verified first.

Tool responses declare output schemas and include structured content. Failures expose a code and retryable indicator. The server does not provide send tools, drafts, forwarding, or permanent deletion paths. Message headers can include the receiving server's recorded SPF, DKIM, and DMARC results, with unchecked results reported as such.

Setup and configuration

Install the csitte/mailwarden MCP server with npx -y mailwarden and configure it as a local stdio MCP process in the client. Gmail authorization is required, and the connected account can be confirmed with get_profile, which returns the account email and mailbox counts.

The optional MAILWARDEN_DOWNLOAD_DIR variable confines downloaded attachments to a directory. If configured, destination paths are resolved within that directory and existing files are not overwritten. Token encryption at rest is also optional through MAILWARDEN_TOKEN_PASSPHRASE; the supplied material does not describe it as required for normal operation.

Filter management requires the gmail.settings.basic scope. If that scope was not included in an earlier authorization, re-run the server's authorization flow. Filter forwarding is not supported; filter actions are limited to Gmail label additions and removals.

Tools and capabilities

• Search and paginate Gmail threads with native query syntax.
• Read thread bodies, headers, and attachment metadata without marking messages read.
• Inspect, create, add, remove, and bulk-apply Gmail labels.
• Archive, trash, restore, mark read, and mark unread threads.
• Snooze, list, unsnooze, and sweep due threads.
• Create, inspect, and delete server-side Gmail filters.
• Download attachments with collision-safe local filenames.
• Generate mailbox triage digests and verify the authorized account.

Limitations and notes

Snoozed messages resurface when sweep_snoozed runs; a timed snooze wakes on the next sweep at or after its target time. Bulk operations can be capped by maxMessages, and affected thread IDs are limited in the response even when the modified count is higher.

untrash removes the Trash label but does not restore the Inbox label. Gmail filters affect new mail unless applyToExisting is requested. The server operates against Gmail and writes attachments locally, but it does not provide a general mailbox export or message-sending workflow.