Gmail MCP Server

Gmail MCP Server (Actively Maintained Fork)

Installation: npx @artymclabin/gmail-mcp auth - or just tell your Claude to install the MCP from this repo (https://github.com/ArtyMcLabin/Gmail-MCP-Server) and let it set up. Prefer manual steps? See Installation & Authentication.

Also on the official MCP Registry (io.github.ArtyMcLabin/Gmail-MCP-Server) and Smithery.

This is an actively maintained fork of [GongRzhe/Gmail-MCP-Server](https://github.com/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](https://github.com/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)
• Durable OAuth sessions - refresh_token is persisted across restarts, ending the hourly re-auth loop (PR #35 by @BrentBaccala)
• Custom OAuth callback port - the auth listener derives port and path from your callback URL instead of hardcoding 3000 (PR #41 by @soapergem)
• Safe permanent-delete gating - delete_email/batch_delete_emails require the opt-in gmail.full scope (which also satisfies all other mail scopes), so default auth stays least-privilege (PR #39 by @caioribeiroclw-pixel)

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

b. Create OAuth 2.0 Credentials:

• Go to "APIs & Services" > "Credentials"
• Click "Create Credentials" > "OAuth client ID"
• Choose either "Desktop app" or "Web application" as application type
• Give it a name and click "Create"
• For Web application, add http://localhost:3000/oauth2callback to the authorized redirect URIs
• Download the JSON file of your client's OAuth keys
• Rename the key file to gcp-oauth.keys.json

1. Run Authentication:

You can authenticate in two ways:

a. Global Authentication (Recommended):

   # First time: Place gcp-oauth.keys.json in your home directory's .gmail-mcp folder

mkdir -p ~/.gmail-mcp mv gcp-oauth.keys.json ~/.gmail-mcp/

Run authentication from anywhere

node dist/index.js auth

b. Local Authentication:

   # Place gcp-oauth.keys.json in your current directory

The file will be automatically copied to global config

node dist/index.js auth

The authentication process will:

• Look for gcp-oauth.keys.json in the current directory or ~/.gmail-mcp/
• If found in current directory, copy it to ~/.gmail-mcp/
• Open your default browser for Google authentication
• Save credentials as ~/.gmail-mcp/credentials.json

Note:

- After successful authentication, credentials are stored globally in ~/.gmail-mcp/ and can be used from any directory

- Both Desktop app and Web application credentials are supported

- For Web application credentials, make sure to add http://localhost:3000/oauth2callback to your authorized redirect URIs

Custom callback URL / port: By default the local OAuth server listens on port 3000 at /oauth2callback. If port 3000 is unavailable, or you need a different redirect URI, pass a full callback URL as an argument. The listener automatically binds to the port and path from that URL:

   node dist/index.js auth http://localhost:8080/oauth2callback

The URL you pass must exactly match one of the authorized redirect URIs registered in the Google Cloud Console.

1. Configure in Claude Desktop:

{

"mcpServers": { "gmail": { "command": "node", "args": [ "/absolute/path/to/Gmail-MCP-Server/dist/index.js" ] } } }

Docker Support

If you prefer using Docker:

1. Authentication:

docker run -i --rm \

--mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \ -v mcp-gmail:/gmail-server \ -e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \ -e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \ -p 3000:3000 \ mcp/gmail auth

1. Usage:

{

"mcpServers": { "gmail": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "mcp-gmail:/gmail-server", "-e", "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json", "mcp/gmail" ] } } }

Cloud Ser