Gmail MCP Server

Community-built Gmail MCP server with OAuth2 auto-auth. Send, draft, search, label, filter, and batch-manage emails through natural language.

Collaboration by GongRzhe (community) OAuth2 active

GitHub Docs npm: @gongrzhe/server-gmail-autoauth-mcp

Overview

The Gmail AutoAuth MCP Server by GongRzhe is the most widely adopted community implementation of a Gmail integration for the Model Context Protocol. It wraps the Gmail API and exposes it to MCP-compatible clients like Claude Desktop, letting AI assistants compose, search, label, filter, and manage email through natural language. It is not an official Google product, but it is distributed on npm and installable via Smithery for one-line setup.

The server covers the full email lifecycle: sending and drafting (including HTML, multipart, attachments up to 25MB, and international characters), reading and downloading attachments, full Gmail search syntax (from:, to:, has:attachment, date ranges), label CRUD operations, and Gmail filter management with templates for common patterns like newsletters and promotions. Batch endpoints can modify or delete up to 50 messages at a time, useful for inbox cleanup automations.

Authentication uses OAuth 2.0 against a Google Cloud project that you create yourself. Credentials are stored locally in ~/.gmail-mcp/ and the server can run via npx or Docker. Because it is community-maintained, behavior and stability depend on the maintainer's release cadence rather than Google's SLA.

Tools

Tool	Description
`send_email`	Send an email immediately
`draft_email`	Create a draft email without sending
`read_email`	Retrieve the content of a specific email
`download_attachment`	Save an email attachment to a local path
`search_emails`	Search inbox using Gmail query syntax
`modify_email`	Add or remove labels on a single email
`delete_email`	Permanently delete a message
`list_email_labels`	List all Gmail labels for the account
`create_label`	Create a new Gmail label
`update_label`	Update an existing label
`delete_label`	Delete a label
`get_or_create_label`	Return a label by name, creating it if missing
`batch_modify_emails`	Add or remove labels across many messages at once
`batch_delete_emails`	Delete many messages in one call
`create_filter`	Create a Gmail filter rule
`list_filters`	List all configured Gmail filters
`get_filter`	Retrieve a specific filter by id
`delete_filter`	Remove a Gmail filter
`create_filter_from_template`	Apply a prebuilt filter template (newsletters, promotions, large files, etc.)

Setup Guide

Prerequisites

Node.js installed locally
A Google Cloud project with the Gmail API enabled
OAuth 2.0 client credentials (Desktop app type recommended)
Port 3000 free for the OAuth callback

Step 1: Create OAuth credentials

In Google Cloud Console, enable the Gmail API.
Create OAuth 2.0 credentials (Desktop application).
Download the JSON file and rename it to gcp-oauth.keys.json.

Step 2: Authenticate

mkdir -p ~/.gmail-mcp
mv gcp-oauth.keys.json ~/.gmail-mcp/
npx @gongrzhe/server-gmail-autoauth-mcp auth

This opens your browser to complete Google sign-in. Tokens are written to ~/.gmail-mcp/credentials.json.

Step 3: Install via Smithery (optional, fastest)

npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude

Step 4: Or add to your MCP client config manually

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["@gongrzhe/server-gmail-autoauth-mcp"]
    }
  }
}

Docker alternative

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

Use Cases

Triage a noisy inbox: search for unread messages from specific senders, summarize them, and apply labels in batch
Draft contextual replies that the human reviews before send_email is invoked
Auto-archive or label newsletters and promotional email using create_filter_from_template
Pull attachments from a thread (invoices, contracts) into a local folder for further processing
Bulk cleanup workflows: batch_delete_emails or batch_modify_emails across hundreds of messages matching a Gmail query

Example Prompts

"Search my inbox for emails from acme.com in the last 7 days and summarize the top 5 threads."
"Draft a reply to the latest email from Sarah confirming the Thursday 2pm meeting, but do not send it."
"Create a label called Investors and apply it to every unread email from anyone at sequoiacap.com."
"Find all emails with attachments larger than 10MB from 2024 and move them to Trash."
"Set up a Gmail filter that auto-archives messages with 'unsubscribe' in the body and labels them Newsletters."

Pros

Broad tool coverage: send, draft, search, labels, filters, batch ops, and attachments in one package
One-line install via Smithery, plus a Docker option
OAuth flow is automated end to end, including auto-refresh of tokens
Supports full Gmail search syntax, HTML/multipart messages, and international characters

Limitations

Community-maintained, not an official Google or Anthropic project, so support and security review are the maintainer's responsibility
Requires you to set up your own Google Cloud project and OAuth credentials, which is non-trivial for non-developers
25MB attachment limit and batch size capped at 50 messages per call

Alternatives

taylorwilsdon/google_workspace_mcp for unified Gmail, Calendar, Drive, Docs, Sheets, and Chat access
shinzo-labs/gmail-mcp as a leaner alternative focused on core Gmail API operations
MarkusPfundstein/mcp-gsuite for Gmail plus Google Calendar in a single server