Back to Browse
Free
Server data from the Official MCP Registry
Native Gmail MCP server: search, labels, archive, trash, attachments, and snooze.
About
Native Gmail MCP server: search, labels, archive, trash, attachments, and snooze.
Security Report
6.6
Moderate6.6Moderate Riskmailwarden is a well-engineered Gmail MCP server with proper OAuth2 authentication, comprehensive input validation, and thoughtful security controls. Code quality is high with extensive test coverage. The server appropriately scopes permissions to Gmail API operations and enforces path traversal protections on file downloads. No critical or high-severity vulnerabilities were identified. Supply chain analysis found 2 known vulnerabilities in dependencies (0 critical, 1 high severity). Package verification found 1 issue.
4 files analyzed · 7 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
Config directory (default ~/.mailwarden), holds credentials.json and token.json
Environment variable: MAILWARDEN_DIR
Path to the Google OAuth credentials.json (Desktop app client)
Environment variable: MAILWARDEN_CREDENTIALS
Set to 1 to sweep due snoozes at startup and hourly while running
Environment variable: MAILWARDEN_AUTO_SWEEP
Restrict download_attachment writes to this directory (recommended for HTTP hosting)
Environment variable: MAILWARDEN_DOWNLOAD_DIR
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-csitte-mailwarden": {
"env": {
"MAILWARDEN_DIR": "your-mailwarden-dir-here",
"MAILWARDEN_AUTO_SWEEP": "your-mailwarden-auto-sweep-here",
"MAILWARDEN_CREDENTIALS": "your-mailwarden-credentials-here",
"MAILWARDEN_DOWNLOAD_DIR": "your-mailwarden-download-dir-here"
},
"args": [
"-y",
"mailwarden"
],
"command": "npx"
}
}
}Documentation
View on GitHubFrom the project's GitHub README.
mailwarden
A reliable, native Gmail MCP server — full mailbox control for AI assistants, with the feature nobody else ships: snooze.
Every operation hits the live Gmail API (no cached snapshot), so it reliably sees all your mail — search, read, label, archive, trash, download attachments, and snooze threads until a date.
Why
Hosted Gmail connectors run on a synced index that can silently miss messages. mailwarden talks straight to the Gmail API, so what you see is what's 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 is sometimes loose for read-state operators — is:unread is silently dropped in some operator combinations (e.g. category:updates is:unread -in:inbox returns read mail too). 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.
Tools
| Tool | What it does |
|---|---|
search | Gmail query syntax → thread summaries (from/subject/date/labels/snippet); read-state/category predicates are re-verified against each hit's live labels |
get_thread | Full thread: headers, plaintext + HTML bodies, attachment metadata |
list_labels | All labels (system + user) |
modify_labels | Add/remove labels (archive = remove INBOX, read = remove UNREAD) |
archive / mark_read / mark_unread | Convenience wrappers |
trash / untrash | Move to / restore from Trash |
download_attachment | Save an attachment to a local path |
snooze | Archive now, resurface on/after a date (YYYY-MM-DD) |
unsnooze | Cancel a snooze, return to inbox now |
list_snoozed | All snoozed threads + due dates |
sweep_snoozed | Resurface threads whose snooze is due (run on demand, via cron, or the daemon) |
How snooze works (no Gmail API snooze exists — we build it)
snooze removes INBOX and applies a dated label MCP/Snoozed/<YYYY-MM-DD>. sweep_snoozed finds due labels and returns those threads to the inbox (marked unread). Run the sweep:
- on demand (
sweep_snoozedtool), - via cron:
mailwarden --sweep, - or automatically: set
MAILWARDEN_AUTO_SWEEP=1(hourly sweep while the server runs).
Quick start
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).
Setup
- Google Cloud: create a project → enable the Gmail API → configure the OAuth consent screen → create an OAuth client ID of type Desktop app → download it as
credentials.json. - Put
credentials.jsonin~/.mailwarden/(or setMAILWARDEN_CREDENTIALS=/path/to/credentials.json). - Authorize once — opens a browser, stores a refresh token in
~/.mailwarden/token.json:
Scope requested:npx -y mailwarden --authhttps://www.googleapis.com/auth/gmail.modify.
Connect
Claude Code (local stdio):
claude mcp add mailwarden -- npx -y mailwarden
Claude Desktop — add to claude_desktop_config.json:
{
"mcpServers": {
"mailwarden": { "command": "npx", "args": ["-y", "mailwarden"] }
}
}
Remote (Streamable HTTP) — for a VPS / claude.ai custom connector:
npx -y mailwarden --http # listens on :8787/mcp ; set PORT, optional MAILWARDEN_TOKEN bearer gate
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.
From source
git clone https://github.com/csitte/mailwarden && cd mailwarden
npm install && npm run build
node dist/index.js --auth
Config (env)
| Var | Meaning |
|---|---|
MAILWARDEN_DIR | config dir (default ~/.mailwarden) |
MAILWARDEN_CREDENTIALS | path to credentials.json |
MAILWARDEN_AUTO_SWEEP | 1 → snooze sweep at startup + hourly while running |
MAILWARDEN_DOWNLOAD_DIR | restrict download_attachment to this directory (strongly recommended for HTTP hosting) |
PORT | HTTP port (default 8787) |
MAILWARDEN_TOKEN | optional bearer token for the HTTP endpoint |
Status
0.1.5 — working. Core Gmail tools + snooze implemented against googleapis and used in daily mailbox automation. Covered by a vitest suite (82 tests, ~99 % statement coverage — npm run coverage). See the changelog / releases. PRs welcome.
License
MIT © C.Sitte Softwaretechnik
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Fetch
Freeby Modelcontextprotocol · Developer Tools
Web content fetching and conversion for efficient LLM usage
80.0K
Stars
8
Installs
5.3
Security
No ratings yet
Local
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
137
Stars
551
Installs
8.0
Security
4.8
Local
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
-
Stars
84
Installs
10.0
Security
4.6
Local