Capability

GongRzhe/Gmail-MCP-Server (original, unmaintained)

ArtyMcLabin/Gmail-MCP-Server (intermediate fork)

klodr/gmail-mcp (this repo)

Core Gmail surface

Send / draft / read / search messages

✅

✅

✅

Label CRUD

✅

✅

✅

Filter CRUD

⚠️ list_filters broken

✅ fixed

✅

Batch modify / delete

✅

✅

✅

Reply threading (In-Reply-To / References)

❌ orphaned replies

✅

✅

Reply-all tool

❌

✅

✅

Send-as alias (from parameter)

❌

✅

✅

Thread-level tools (get_thread, list_inbox_threads, get_inbox_with_threads)

❌

✅

✅

Download email to disk (json/eml/txt/html)

❌

✅

✅

Download attachment

✅

✅

✅

OAuth / authorization

--scopes flag for least-privilege auth

❌

✅

✅

Tool list filtered by granted scopes

❌

✅

✅

OAuth credentials file mode 0o600

❌

✅

✅

Security — input handling

CRLF header injection sanitization (\r\n\0)

❌

⚠️ partial

✅

Path traversal in download_attachment

❌

✅ fixed

✅

Attachment source jail (GMAIL_MCP_ATTACHMENT_DIR) blocks exfiltration of ~/.ssh/id_rsa etc. via prompt injection

❌

❌

✅

Download destination jail (GMAIL_MCP_DOWNLOAD_DIR)

❌

❌

✅

O_NOFOLLOW on leaf writes (pre-existing symlink at destination rejected)

❌

❌

✅

Post-mkdir realpath re-verification (TOCTOU defense)

❌

❌

✅

Zod bounds on maxResults / batchSize / messageIds length

❌

❌

✅

Cryptographic MIME boundary (crypto.randomBytes, not Math.random)

❌

❌

✅

MCP protocol & tool surface

MCP SDK version

v0.4.x

v1.27.x

v1.29.x

Tool annotations (readOnlyHint / destructiveHint / idempotentHint)

❌

✅

✅

llms-install.md (LLM-readable install guide)

❌

❌

✅

Publishing / discoverability

Published on npm

❌ stale — no future releases (repo archived)

❌ (consumed as a GitHub install from the intermediate fork)

✅ dedicated scoped package, signed releases

Active maintenance (last 30 d)

❌ (archived 2026-03-03)

⚠️ sporadic

✅ daily review cycle (CodeRabbit + human)

Supply-chain integrity

Node.js floor

❌ >=14 (EOL April 2023)

❌ >=14 (EOL April 2023)

✅ >=22 (Active LTS, maintenance until 2027-04-30)

CI: CodeQL Advanced (javascript-typescript + actions)

❌

❌

✅

CI: OpenSSF Scorecard (weekly scan + badge)

❌

❌

✅

CI: Socket Security supply-chain alerts

❌

❌

✅

CI: CodeRabbit assertive reviews on every PR

❌

❌

✅

Release: Sigstore-signed dist/index.js + SLSA in-toto attestation

❌

❌

✅

Release: npm provenance statement

❌

❌

✅

Release: single-file ESM bundle

❌

❌

✅

Testing

Unit/property tests

❌ (0 tests)

⚠️ (97 tests)

✅ (631 tests)

Statement coverage across src/**

0%

16.14%

>97%

Fast-check property-based fuzz suite

❌

❌

✅

Hardening-specific test file (jails, CRLF, O_EXCL)

❌

❌

✅

CI/CD hardening

Shell-injection-safe GitHub Actions workflows

❌

✅

✅

Workflows use least-privilege permissions: scopes

❌

✅

✅

All GitHub Actions pinned by full commit SHA

❌

❌

✅

Operational

CHANGELOG.md (Keep-a-Changelog)

❌

❌

✅

SECURITY.md (vulnerability reporting)

❌

❌

✅

Scope shorthand

Full Gmail scope

What it grants

gmail.readonly

…/auth/gmail.readonly

Read messages, threads, labels (filter tools require gmail.settings.basic)

gmail.modify

…/auth/gmail.modify

Readonly + apply/remove labels, delete messages

gmail.compose

…/auth/gmail.compose

Create drafts

gmail.send

…/auth/gmail.send

Send messages

gmail.labels

…/auth/gmail.labels

Manage labels only

gmail.settings.basic

…/auth/gmail.settings.basic

Manage filters

Knob

Env var

Default

Notes

Attachment jail

GMAIL_MCP_ATTACHMENT_DIR=/abs/path

~/GmailAttachments/ (auto-created mode 0o700)

Every attachment path (send_email, draft_email, update_draft, reply_all, reply_to_email, forward_email) must live inside this directory after realpath canonicalization. Symlinks pointing outside are rejected. Blocks prompt-injected exfiltration of ~/.ssh/id_rsa, ~/.gmail-mcp/credentials.json, ~/.claude.json, etc.

Download jail

GMAIL_MCP_DOWNLOAD_DIR=/abs/path

~/GmailDownloads/ (auto-created mode 0o700)

download_email and download_attachment write exclusively here. The leaf is opened with O_NOFOLLOW; post-mkdir the resolved path is re-verified against the jail root (TOCTOU defense).

OAuth keys path

GMAIL_OAUTH_PATH=/abs/path/gcp-oauth.keys.json

~/.gmail-mcp/gcp-oauth.keys.json

Google Desktop/Web OAuth client credentials.

Credentials path

GMAIL_CREDENTIALS_PATH=/abs/path/credentials.json

~/.gmail-mcp/credentials.json

Access/refresh tokens. File mode 0o600.

Rate limit state dir

GMAIL_MCP_STATE_DIR=/abs/path

~/.gmail-mcp/

Where the rolling call-history for rate limiting is persisted (ratelimit.json, mode 0o600). Same directory is reused for any future state files.

Rate limit overrides

GMAIL_MCP_RATE_LIMIT_<bucket>=D/day,M/month

see below

Override the per-bucket daily/monthly caps. Buckets: send (100/2000), delete (200/2000), modify (500/5000), drafts (300/3000), labels (50/500), filters (20/200). The send cap is sized at the upper end of a human professional workload (~40 emails/day with a 2.5× cushion); raise it via GMAIL_MCP_RATE_LIMIT_send=400/day,6000/month if you need the pre-v0.30.2 default. The bucket name is lowercase and matches the tool family.

Rate limit disable

GMAIL_MCP_RATE_LIMIT_DISABLE=true

unset (limiter active)

Kill-switch for the entire limiter. Use only for test suites or controlled batch operations.

Audit log

GMAIL_MCP_AUDIT_LOG=/abs/path/audit.jsonl

unset (no audit trail)

Opt-in append-only JSONL log of every tool call (name, redacted args, outcome). File mode 0o600. Must be an absolute path; relative paths are rejected at startup. Redaction keeps structural keys and drops values under an allowlist.

Dry-run

GMAIL_MCP_DRY_RUN=true

unset (real calls)

When "true" (strict match), every write tool (send_email, reply_all, reply_to_email, forward_email, draft_email, update_draft, delete_draft, send_draft, delete_email, modify_email, batch_modify_emails, batch_delete_emails, create_label, update_label, delete_label, get_or_create_label, create_filter, delete_filter, create_filter_from_template, modify_thread) short-circuits before reaching Gmail and returns the redacted payload it would have sent. Useful for CI smoke tests, agent debugging, and human-in-the-loop approval flows. Read tools ignore the flag (nothing to preview). Matches MERCURY_MCP_DRY_RUN / FAXDROP_MCP_DRY_RUN on the sibling servers.