📧 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.

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.

✨ 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) a modern supply chain (Scorecard, Socket, Sigstore), and (c) an in-repo review policy (.coderabbit.yaml) that every PR must pass before merge.

Related MCP server: mercury-invoicing-mcp

📦 Installation

npm install -g @klodr/gmail-mcp

Or directly via npx:

npx -y @klodr/gmail-mcp

Requires Node.js 22+.

⚙️ 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 — resolves the from parameter against the account's authorized send-as aliases only. Spoofing the sender field is rejected before the Gmail API send call.

• rate-limit.ts — bounds Gmail API call volume per tool family (send, delete, modify, drafts, labels, filters) over rolling daily/monthly windows. The state is persisted to disk so it survives restarts. Disable with GMAIL_MCP_RATE_LIMIT_DISABLE=true for test runs only.

• gmail-errors.ts — normalizes Gmail API failure modes into typed errors so retries and surfacing to the LLM are deterministic.

• middleware.ts — composes the always-on chain and binds it to every tool entry point. New tools inherit the pipeline by construction.

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 family only.

• 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, 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.