📧 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.
Potencialize seu agente
O comando do próprio publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
npx -y @klodr/[email protected]O Claude Code não tem link de instalação para um comando local. Copie o comando abaixo e execute-o em um terminal.
claude mcp add klodr-gmail-mcp -- npx -y @klodr/gmail-mcp@3.0.1Execute em um terminal.
{ "mcpServers": { "klodr-gmail-mcp": { "command": "npx", "args": [ "-y", "@klodr/[email protected]" ] } }}claude_desktop_config.json
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDo publicador
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.
Gmail MCP server — scope-gated tools + attachment/download path jails + supply-chain hardening. Fork of GongRzhe/Gmail-MCP-Server via ArtyMcLabin's intermediate fork.
[!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-mcpis 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.
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).
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).
http://localhost:3000/oauth2callback to the authorized redirect URIs.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).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).
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": ["-y", "@klodr/gmail-mcp"]
}
}
}
Client-specific config file:
~/.claude.json~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)~/.cursor/mcp.json~/.openclaw/openclaw.jsonSee llms-install.md for an LLM-readable install guide.
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
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.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 --scopes grants it. Create those in the Gmail web interface.email-export.ts) — the file download_email writes in html format carries a Content-Security-Policy blocking scripts, plugins, frames, <base> rewrites and form submissions, and by default every remote fetch — images, stylesheets, fonts, media and the rest (default-src 'none') — so a tracking pixel or stylesheet cannot report when and where the copy is opened (inline styles and images still render); a sender's <meta http-equiv="refresh"> is neutralized. Allow remote content per call with allowRemoteImages: true or globally with GMAIL_MCP_EXPORT_REMOTE_IMAGES=true.send_draft recipient check — the staged draft is read before sending, and a To / Cc / Bcc header that does not parse as a list of addresses is refused, so a draft's destination is always known.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 / 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:
The exact set depends on the OAuth scopes granted at auth time. Full catalog:
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_emaillist_drafts, get_draft, update_draft, delete_draft, send_draft (full users.drafts.* surface; draft_email above creates the initial draft)get_thread, list_inbox_threads, get_inbox_with_threads, modify_threadlist_email_labels, create_label, update_label, delete_label, get_or_create_labellist_filters, get_filter, create_filter, delete_filter, create_filter_from_templatepair_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 syntaxsearch_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 after:2026/01/01 has:attachment. Full reference: Google's Gmail search operators cheat sheet. A query that matches nothing returns No messages found for query: <query> rather than an empty result.
See ROADMAP.md.
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.
See CONTRIBUTING.md for the test / build / lint checklist and release process.
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.
See CONTINUITY.md for the handover plan if the maintainer becomes unavailable.
MIT — see LICENSE.
klodr/gmail-mcp is the maintenance fork of a two-step upstream chain:
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.
Gmail MCP server — scope-gated tools + attachment/download path jails + supply-chain hardening. Fork of GongRzhe/Gmail-MCP-Server via ArtyMcLabin's intermediate fork.
{ "mcpServers": { "klodr-gmail-mcp": { "command": "npx", "args": [ "-y", "@klodr/[email protected]" ] } }}Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
@klodr/gmail roda localmente via stdio.
Última verificação: 2026-11-16. Gmail MCP server — scope-gated tools + attachment/download path jails + supply-chain hardening. Fork of GongRzhe/Gmail-MCP-Server via ArtyMcLabin's intermediate fork.