Gmail AutoAuth MCP Server (Actively Maintained Fork)

Installation: just tell your Claude to install the MCP from this repo - point it at https://github.com/ArtyMcLabin/Gmail-MCP-Server and let it set up. Prefer manual steps? See Installation & Authentication.

> This is an actively maintained fork of GongRzhe/Gmail-MCP-Server.
>
> The original repository has been unmaintained since August 2025 - 7+ months with zero maintainer activity and 72+ unmerged pull requests. I use this MCP server daily as part of my Claude Code workflow and depend on it working correctly, so I picked it up.
>
> Pull requests are welcome. If you've been sitting on fixes or features with nowhere to submit them, this is the place.

Philosophy

This fork is lean and pragmatic. It's a local stdio MCP server - you run it on your own machine, and your LLM client already has shell + filesystem access. So the threat model is "don't leak credentials to third parties, don't break the Gmail surface" - not "defend a hosted multi-tenant service". I keep dependencies minimal. I use this daily in my own Claude Code workflow - if I wouldn't run it or maintain it myself, it doesn't go in.

There's a downstream fork that took this in the maximalist direction. I'm not affiliated with its maintainer and I don't track its security or features - use it at your own risk: klodr/gmail-mcp. If that's the philosophy you want, go check it out. PRs welcome here as always.

What this fork adds

- Fixed reply threading - auto-resolves In-Reply-To and References headers so email replies land in the correct thread instead of creating orphaned messages (upstream PR #91, still pending)
- Send-as alias support - optional from parameter for multi-identity email management (send from any configured Gmail alias)
- Reply-all tool - reply_all automatically fetches the original email, builds To/CC recipient lists (excluding yourself), and sets proper threading headers (PR #3 by @MaxGhenis)
- Fixed list_filters - was returning empty array due to wrong response property name (PR #4 by @nicholas-anthony-ai)
- Custom OAuth2 scoping - --scopes flag to request only the permissions you need, with automatic tool filtering (PR #6 by @tansanDOTeth)
- CI/CD hardening - fixed shell injection vector in GitHub Actions workflow, added least-privilege permissions scope (PR #9 by @JF10R)
- Security hardening - fixed path traversal in attachment download, restricted OAuth credential file permissions (PR #10 by @JF10R)
- Dependency security - upgraded MCP SDK to v1.27.1 (3 CVE fixes), upgraded nodemailer (DoS + routing fix), moved dev-only packages out of production deps (PR #11 by @JF10R)
- Thread-level tools - get_thread, list_inbox_threads, get_inbox_with_threads, modify_thread for efficient thread-based email operations in a single call
- CC/BCC visibility - read_email now shows CC and BCC headers when present (PR #21 by @panghy)
- Phishing report tools - report_phishing and batch_report_phishing for marking messages as spam via the Gmail API (PR #24 by @ShivamB25)
- Draft lifecycle tools - send_draft, delete_draft, update_draft close the orphan-draft gap: send_draft atomically sends an existing draft and removes it from Drafts (no ghost copy); update_draft mutates a draft in place preserving its ID (no draft pile-up across iteration loops); delete_draft discards an abandoned draft (PR #30 by @thisisambros)
- Tool annotations - MCP spec annotations (readOnlyHint, destructiveHint, idempotentHint) on all tools for safer LLM tool execution (PR #14 by @bryankthompson)
- Download email tool - download_email saves emails to disk in json/eml/txt/html formats without consuming LLM context (PR #13 by @icanhasjonas)

All features are production-tested in daily use.

---

A Model Context Protocol (MCP) server for Gmail integration in Claude Desktop with auto authentication support. This server enables AI assistants to manage Gmail through natural language interactions.


Features

- Send emails with subject, content, attachments, and recipients
- Full attachment support - send and receive file attachments
- Download email attachments to local filesystem
- Download full emails to files in json/eml/txt/html formats
- Thread-level operations - get full threads, list inbox threads, batch-expand threads
- Support for HTML emails and multipart messages with both HTML and plain text versions
- Full support for international characters in subject lines and email content
- Read email messages by ID with advanced MIME structure handling
- Enhanced attachment display showing filenames, types, sizes, and download IDs
- Search emails with various criteria (subject, sender, date range)
- Comprehensive label management with ability to create, update, delete and list labels
- List all available Gmail labels (system and user-defined)
- List emails in inbox, sent, or custom labels
- Mark emails as read/unread
- Move emails to different labels/folders
- Delete emails
- Batch operations for efficiently processing multiple emails at once
- Full integration with Gmail API
- Simple OAuth2 authentication flow with auto browser launch
- Support for both Desktop and Web application credentials
- Global credential storage for convenience

Installation & Authentication

Installing from npm (recommended)

npx @artymclabin/gmail-mcp auth

Installing from source

git clone https://github.com/ArtyMcLabin/Gmail-MCP-Server.git
cd Gmail-MCP-Server
npm install
npm run build

> Note: The npx @gongrzhe/server-gmail-autoauth-mcp commands found in older docs reference the unmaintained upstream fork. This fork is published as @artymclabin/gmail-mcp.

Setting up Google Cloud credentials

1. Create a Google Cloud Project and obtain credentials:

a. Create a Google Cloud Project:
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the Gmail API for your project

…