Gmail AutoAuth MCP Server: Control Gmail via Claude Desktop

The Gmail AutoAuth MCP Server integrates Gmail directly into Claude Desktop. Built on the Model Context Protocol, this server manages OAuth2 authentication automatically, turning Claude into a natural-language interface for your inbox. Users can search, read, draft, and organize emails without ever leaving the chat interface.

Key Capabilities

Send Emails: Draft and send messages complete with subject lines, body text, attachments, and multiple recipients. The server supports plain text, HTML, and multipart alternative formats. It ensures international characters in subject lines and bodies are rendered correctly across all clients.

Read and Search: Retrieve specific messages by ID with clean parsing of complex MIME structures. Claude can search your inbox using senders, subject lines, date ranges, or any standard Gmail search operator.

Label Management: Create, rename, or delete labels. The server handles both system labels (Inbox, Sent, Trash) and custom user labels. You can also mark messages as read/unread or move them between folders via the chat interface.

Batch Operations: Modify or delete dozens of emails simultaneously. The server includes built-in chunking logic to ensure operations stay within Gmail API limits.

Authentication Flow: Full Gmail API integration featuring a streamlined OAuth2 consent process. Once configured, credentials are stored globally, so you only need to complete the setup once.

Installation and Authentication

Install via Smithery

To automatically install and configure the server for Claude Desktop, run the following command:

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

Manual Setup

1. Create a Google Cloud Project

   • Visit the Google Cloud Console, create a new project, and enable the Gmail API.
   • Go to APIs & Services > Credentials and select Create Credentials > OAuth client ID.
   • Choose Desktop app (or Web application) and name it.
   • If using a web application, add http://localhost:3000/oauth2callback to the Authorized redirect URIs.
   • Download the client secret JSON file and rename it to gcp-oauth.keys.json.

2. Run Authentication

   • Global Auth (Recommended): Create a .gmail-mcp folder in your home directory and place gcp-oauth.keys.json inside. Then execute:

     npx @gongrzhe/server-gmail-autoauth-mcp auth
     

   • Local Auth: Place gcp-oauth.keys.json in your current working directory and run the same command. The file will automatically copy itself to ~/.gmail-mcp/.

The authentication process searches for the key file in your current folder or ~/.gmail-mcp/. It will open your default browser for Google sign-in. After access is granted, your credentials will be saved to ~/.gmail-mcp/credentials.json.

Configure Claude Desktop

Add the following configuration to your Claude Desktop settings file:

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

Docker Support

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

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 Server Authentication

For remote environments (such as n8n) where localhost is inaccessible, you can specify a custom callback URL:

npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback

Cloud Setup Steps

1. Reverse Proxy: Expose the authentication port from your container and proxy traffic from your domain (e.g., gmail.gongrzhe.com) to that port.
2. DNS: Configure an A record pointing your domain to the server's IP address.
3. Google Cloud Console: Add https://gmail.gongrzhe.com/oauth2callback to your authorized redirect URIs.
4. Execute Auth: Run the authentication command using your custom callback URL.
5. Configure Client: Update your MCP settings using the same pattern as Claude Desktop.

This allows the OAuth flow to complete on a remote server successfully.

Available Tools

The server provides the following tools to Claude:

1. send_email: Sends a message immediately. Supports plain text, HTML, and multipart (HTML with plain text fallback).
2. draft_email: Creates a message in your drafts folder without sending it.
3. read_email: Retrieves the full content of a specific message using its ID.
4. search_emails: Finds messages using standard Gmail search syntax.
5. modify_email: Adds or removes labels from a specific message.
6. delete_email: Permanently deletes a message.
7. list_email_labels: Returns all available Gmail labels.
8. create_label: Generates a new custom label with specific visibility settings.
9. update_label: Renames existing labels or modifies their visibility.
10. delete_label: Removes a custom label.
11. get_or_create_label: Finds a label by name or creates it if it does not exist.
12. batch_modify_emails: Applies label changes to multiple messages simultaneously with configurable batch sizes.
13. batch_delete_emails: Permanently deletes multiple messages in a single operation.

Advanced Search Operators

The search_emails tool utilizes Gmail's native query engine:

You can combine these for precise results: from:[email protected] after:2024/01/01 has:attachment.

Advanced Features

Intelligent Content Extraction The server processes complex MIME trees by prioritizing plain text and falling back to HTML when necessary. It accurately handles nested multipart messages and preserves essential metadata like sender details, recipients, and timestamps.

Internationalization Subject lines and message bodies fully support non-ASCII characters. Whether your emails are in Chinese, Japanese, Arabic, or European languages with diacritics, the text will render accurately.

Granular Label Management Claude can manage mailbox organization via custom visibility settings:

• messageListVisibility: Set to show or hide labels in the message list.
• labelListVisibility: Choose between labelShow, labelShowIfUnread, or labelHide.

Batch Processing Power The server handles up to 50 messages per batch by default. It automatically segments large requests to stay within API rate limits and provides a detailed success/failure report for each item, including automatic retries for individual failures.

Security

OAuth credentials are stored locally in ~/.gmail-mcp/. The server utilizes "offline access" to maintain authentication without repeated logins. These files contain sensitive access tokens and should never be committed to version control. You can review or revoke these permissions at any time via your Google Account security settings.

Troubleshooting

• OAuth Keys Not Found: Ensure gcp-oauth.keys.json is located in the active directory or ~/.gmail-mcp/. Verify that the file has the correct read permissions.
• Invalid Credentials Format: Confirm the JSON file contains either web or installed credential blocks. If using a web app, ensure the redirect URI matches your Google Cloud settings exactly.
• Port Conflict: If port 3000 is occupied, the authentication flow will fail. Close any applications using this port before starting the auth process.
• Batch Failures: If a batch operation fails, check the returned error log. Frequent failures may require reducing the batchSize to avoid rate limiting.