Gmail MCP README

📧 gmail-mcp

Read, search, send, draft, label, filter, and thread Gmail from any MCP-enabled AI assistant. Wraps the Gmail API with scope-gated tools and in-process safeguards.

[!NOTE] Hardened + enhanced fork of GongRzhe/Gmail-MCP-Server (archived 2026-03-03), via ArtyMcLabin/Gmail-MCP-Server. Since the divergence point: 180+ commits and an extensive rewrite — security hardening, Gmail-surface improvements (reply-all, send-as alias, thread-level tools, download-to-disk, recipient pairing, batch ops with retry…), supply-chain hygiene, and CI gating. Every PR goes through CodeRabbit + dual-model Qodo Merge before merge. See SECURITY.md for the controls and threat model, and the comparison table below for the parent-forks delta.

A Model Context Protocol (MCP) server that lets AI assistants (Claude Desktop, Claude Code, Cursor, Continue, OpenClaw…) read and manage a Gmail account through scope-gated tools. Exposes the Gmail v1 API surface you actually need (messages, threads, labels, filters, attachments, drafts, reply-all) behind a single npx install.

[!IMPORTANT] Positioning. Upstream calls this fork the maximalist one. The label is accurate from the outside, but it misframes the intent. klodr/gmail-mcp is built around four properties — and the code, tests and CI/CD all exist to pay rent on these and only these:

• Secure — input sanitization, recipient pairing, rate limiting, sender resolution, and audit logging are enforced in the server (not in the operator's attention). The Gmail surface is mediated, not exposed raw.
• Autonomous — designed to stay safe when no human is watching every action. Different threat model from upstream's "I use it daily in my own workflow"; the in-process middleware is what bridges that gap.
• Tested — 945 vitest cases across 43 files, 99.37% statement coverage (91% branch), plus a fast-check property-based fuzz suite and a dedicated hardening test file.
• Resilient under acceleration — 17 CI/CD workflows (CodeQL, OSV, Gitleaks, leak-detect, Scorecard, Socket, SLSA, lockfile lint, signed releases…) track the security ecosystem at the pace it actually changes — days, sometimes hours. Recent concrete instance: qs CVE-2026-8723, surfaced and shipped within hours of the public advisory across the klodr/* MCP family.

Full rationale and the per-tool design trade-offs live in docs/DESIGN_DECISIONS.md.

✨ Why this MCP?

Comparison of the three maintained forks of the original Gmail MCP server, focusing on what an agent platform actually needs — prompt-injection safety, supply-chain integrity, and operational hygiene:

klodr/gmail-mcp is the only one of the three with (a) source-path jails that make prompt-injection attachment exfiltration inert, (b) outbound guard rails a hostile email cannot talk the model past — an optional recipient allowlist the model cannot extend through gmail-mcp, no forwarding filters, write caps that count every message — (c) a modern supply chain (Scorecard, Socket, Sigstore), and (d) an in-repo review policy (.coderabbit.yaml) that every PR must pass before merge.

Fork columns checked against the code of GongRzhe a890d19 (2025-08-06, archived) and ArtyMcLabin 83e8daf (main, 2026-08-12).

📦 Installation

npm install -g @klodr/gmail-mcp

Or directly via npx:

npx -y @klodr/gmail-mcp

Requires Node.js 24.18.1+ (tested on Node 24 and 26).

⚙️ Configuration

1️⃣ Google Cloud OAuth credentials

1. Open the Google Cloud Console.
2. Create a project and enable the Gmail API.
3. Under APIs & Services → Credentials, create an OAuth 2.0 Client ID (Desktop or Web). For Web, add http://localhost:3000/oauth2callback to the authorized redirect URIs.
4. Download the JSON, rename it to gcp-oauth.keys.json, place it at ~/.gmail-mcp/gcp-oauth.keys.json (or override with GMAIL_OAUTH_PATH=/abs/path/gcp-oauth.keys.json).

2️⃣ Authenticate (once)

npx -y @klodr/gmail-mcp auth --scopes=gmail.readonly

Always pass --scopes with the minimum you actually need — the MCP filters the tool list at startup based on the granted scopes, so a read-only token doesn't expose write tools to the LLM. A browser opens for Google's consent flow; tokens are written to ~/.gmail-mcp/credentials.json (mode 0o600).

3️⃣ Register the server with your MCP client

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@klodr/gmail-mcp"]
    }
  }
}

Client-specific config file:

• Claude Code: ~/.claude.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Cursor: ~/.cursor/mcp.json
• OpenClaw: ~/.openclaw/openclaw.json

See llms-install.md for an LLM-readable install guide.

🔑 OAuth scopes

Recipes:

# Read-only browsing
npx @klodr/gmail-mcp auth --scopes=gmail.readonly

# Read + send (mailing-list bot)
npx @klodr/gmail-mcp auth --scopes=gmail.readonly,gmail.send

# Everything (default; explicit)
npx @klodr/gmail-mcp auth --scopes=gmail.modify,gmail.settings.basic

# Default + permanent delete (delete_email / batch_delete_emails)
# gmail.modify authorizes trash; mail.google.com is the only scope
# that authorizes purging from Trash. Both are listed because the
# tool gate does exact scope-name matching — a token holding only
# mail.google.com would not enable the gmail.modify-gated tools,
# even though Google's scope hierarchy would technically accept the
# same calls.
npx @klodr/gmail-mcp auth --scopes=gmail.modify,mail.google.com,gmail.settings.basic

🛡️ Safeguards

In-process middleware (autonomy enforcement)

The runtime constraints that an autonomous LLM client cannot violate are enforced in the server, not in the operator's attention span. Seven in-process modules sit on the tool entry path; the ones that are opt-in only activate when the matching env var is set.

Always-on (active for every call out of the box):

• sanitize.ts — strips/escapes input the LLM provides (CRLF injection, control characters, NUL bytes) before it reaches Gmail headers, filenames, or filesystem paths.
• sender-resolver.ts — when the send-as list is readable and non-empty, resolves the from parameter against the account's authorized send-as aliases only, so spoofing the sender field is rejected before the Gmail API send call; when the list is unavailable or empty, an explicit from passes through unchanged. Without from, and when the send-as list is readable, a reply, a forward or a threaded send_email / draft_email leaves from the alias the conversation already uses (the one the source message came from or was sent to, else the last one used in the thread), as in the Gmail web UI, and reply_all never copies any of the account's aliases. When the list is unavailable (e.g. a token limited to gmail.send or gmail.compose), the sender falls back to resolveDefaultSender and reply_all leaves out only the account's own address.
• rate-limit.ts — bounds write volume per tool family (send, delete, modify, drafts, labels, filters, pairing) over rolling daily/monthly windows. The batch tools (batch_modify_emails, batch_delete_emails, move_to_spam_batch) count each message they touch, so one call on 1 000 messages uses 1 000 units, not 1. The state is persisted to disk so it survives restarts. Disable with GMAIL_MCP_RATE_LIMIT_DISABLE=true for test runs only.
• quarantine.ts — marks every file written by download_attachment, download_all_attachments and download_email as downloaded from the internet, as Mail and Outlook do: the com.apple.quarantine attribute on macOS (Gatekeeper checks an executable or script when it is opened), the Mark of the Web on Windows; nothing on Linux. Never blocking: if the mark cannot be set, the file is still saved. Off with GMAIL_MCP_QUARANTINE=false.
• Forwarding filters refused (filter-manager.ts) — create_filter and the filter templates never install a rule that forwards mail: such a rule silently redirects every future matching message, and Gmail forwards only to a verified forwarding address, whose registration needs the gmail.settings.sharing scope — not in the default scopes and used by no tool here; the refusal holds even if grants it. Create those in the Gmail web interface.

Opt-in (off by default, set the env var to engage):

• recipient-pairing.ts — refuses to send mail to addresses that are not on the operator-controlled allow-list (~/.gmail-mcp/paired.json). No fresh outbound destinations from a hallucinated address. Engages when GMAIL_MCP_RECIPIENT_PAIRING=true; gates the send_email / reply_* / forward_email / draft_email / update_draft / send_draft family. Addresses are compared bare (Name <address> matches the paired address). While the gate is on, the model cannot extend the list through gmail-mcp: pair_recipient add asks the human to confirm through the MCP client (elicitation) and, where the client cannot ask, refuses and names the terminal command — npx @klodr/gmail-mcp pair add <address> (also pair remove, pair list). Otherwise a hostile email could tell the agent to pair its own address, then write to it. The guarantee covers the gmail-mcp surface: it holds as long as the MCP client does not also let the model run terminal commands (such as npx @klodr/gmail-mcp pair add) or write paired.json without your approval.
• audit-log.ts — append-only JSONL trail of every tool call (name, redacted args, outcome) with structural-key-preserving redaction so operators can replay decisions post-hoc. Engages when GMAIL_MCP_AUDIT_LOG=/abs/path/audit.jsonl is set.

Configure each module via the env vars below:

🛠️ Tools

The exact set depends on the OAuth scopes granted at auth time. Full catalog:

• Messages — send_email, draft_email, read_email, search_emails, modify_email, delete_email, download_email, download_attachment, download_all_attachments, batch_modify_emails, batch_delete_emails, reply_all, reply_to_email, forward_email
• Drafts — list_drafts, get_draft, update_draft, delete_draft, send_draft (full users.drafts.* surface; draft_email above creates the initial draft)
• Threads — get_thread, list_inbox_threads, get_inbox_with_threads, modify_thread
• Labels — list_email_labels, create_label, update_label, delete_label, get_or_create_label
• Filters — list_filters, get_filter, create_filter, delete_filter, create_filter_from_template
• Recipient pairing — pair_recipient (manage the ~/.gmail-mcp/paired.json allowlist when GMAIL_MCP_RECIPIENT_PAIRING=true)

Every write tool is annotated with destructiveHint / readOnlyHint / idempotentHint per the MCP spec so policy-aware clients can gate on HITL confirmation.

🔍 search_emails query syntax

search_emails accepts Gmail's native search operators — from:, to:, subject:, has:attachment, after:YYYY/MM/DD, before:YYYY/MM/DD, is:unread, label:<name>, etc. They combine freely: from:alice@example.com after:2026/01/01 has:attachment. Full reference: Google's Gmail search operators cheat sheet.

🗺️ Roadmap

See ROADMAP.md.

🌐 Ecosystem

Other MCP servers in the klodr family

• 📧 klodr/gmail-mcp — Gmail (you are here)
• 📠 klodr/faxdrop-mcp — Send real faxes via FaxDrop
• 🏦 klodr/mercury-invoicing-mcp — Mercury banking + invoicing

Wider Gmail-MCP landscape

29 standalone repositories and 349 forks of the original GongRzhe server are reviewed in docs/COMPETITORS.md — which ideas we borrowed, which we chose not to, and where klodr/gmail-mcp sits on the maturity axes.

🤝 Contributing

See CONTRIBUTING.md for the test / build / lint checklist and release process.

🔒 Security

See SECURITY.md for the vulnerability-reporting process and the current security model, and ASSURANCE_CASE.md for the threat model, trust boundaries, and CWE/OWASP mitigation table.

📋 Project continuity

See CONTINUITY.md for the handover plan if the maintainer becomes unavailable.

📄 License

MIT — see LICENSE.

📜 History

klodr/gmail-mcp is the maintenance fork of a two-step upstream chain:

• GongRzhe/Gmail-MCP-Server — the original server. Unmaintained since August 2025 (7+ months with zero maintainer activity and 72+ unmerged pull requests).
• ArtyMcLabin/Gmail-MCP-Server — Arty MacKiewicz's active fork. Since divergence from Gong, it merged community contributions including: reply-all (#3 by @MaxGhenis), list_filters fix (#4 by @nicholas-anthony-ai), CI/CD shell-injection hardening (#9 by @JF10R), download_email (#13 by @icanhasjonas), tool annotations (#14 by @bryankthompson), CC/BCC fields in read_email (#21 by @panghy), and draft lifecycle tools send_draft / delete_draft / update_draft (#30 by @thisisambros). Reply-threading auto-resolution and the --scopes flag were folded in directly by the maintainer.

klodr/gmail-mcp carries all of the above forward and adds the supply-chain / path-jail / review-policy layer (see comparison table above). Credit to every PR author along the chain.