Gmail AutoAuth

You can manage Gmail from Claude Desktop through a dedicated MCP Server that handles authentication automatically and provides a rich set of Gmail operations. With this server, you can send, read, search, label, and batch-process emails directly from your AI workflows, while benefiting from robust Gmail API integration and convenient credential handling.

How to use

To use the Gmail MCP Server, install it in your Claude Desktop environment and configure it as an MCP server you can call from Claude. The server exposes a set of tools that let you send emails, draft messages, read inbox content, manage labels, perform searches, and perform batch operations.

Key usage patterns include: creating and sending emails with attachments, reading specific messages by ID, searching messages with Gmail syntax, and managing labels (create, update, delete, list, or get-or-create). You can also perform batch modifications or deletions to handle multiple messages efficiently. All actions are mediated through natural language prompts in Claude, but they translate into precise Gmail API operations under the hood.

Authentication is streamlined via an auto browser flow. You will authenticate once, after which credentials are stored locally and reused for subsequent requests. If you operate in a cloud or container environment, you can use a custom callback URL to complete the OAuth flow from remote contexts.

How to install

Prerequisites you need before installing: a Node.js and npm environment so you can run npm or npx commands, and access to Claude Desktop for configuring the MCP server.

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

Install the MCP server into Claude Desktop using the standard CLI. This example uses npx to run the MCP package directly. You can also install via the Docker workflow if you prefer containerized usage.

If you want to authenticate globally (recommended), place your OAuth keys file in the designated global config directory and then run the authentication command from anywhere.

Global authentication flow (examples):

# Place the Google OAuth keys in the global config directory (example path shown)
mkdir -p ~/.gmail-mcp
mv gcp-oauth.keys.json ~/.gmail-mcp/

# Run authentication from anywhere
npx @gongrzhe/server-gmail-autoauth-mcp auth

Local authentication flow (examples):

# Place the Google OAuth keys in your current directory
# The tool will copy it to the global config automatically
npx @gongrzhe/server-gmail-autoauth-mcp auth

Cloud or custom-domain authentication support is available by providing a callback URL during the auth step, enabling flows where localhost is not accessible.

Additional configuration and notes

Security: OAuth credentials are stored locally in the user’s environment under a dedicated folder. The server uses offline access to maintain persistent authentication. Do not share credentials or commit them to version control.

Docker-based usage is supported. You can run authentication inside a container and configure the container to map credentials and data paths as shown in the Docker examples.

If you operate in a cloud environment, you can specify a custom callback URL when authenticating, for example to support domains outside localhost.

Troubleshooting

OAuth Keys Not Found: Ensure gcp-oauth.keys.json is in the current directory or in the global ~/.gmail-mcp directory. Check file permissions.

Invalid Credentials Format: The keys file must contain valid web or installed credentials and, for web apps, the redirect URI must be correctly configured.

Port conflicts during local auth: If port 3000 is in use, free it up before starting authentication.

Batch operation failures: The system will retry items individually if a batch fails. If you encounter rate limits, reduce the batch size.

Notes on usage and capabilities

The server provides a full Gmail API integration with rich label management, including creating, updating, deleting, and listing labels, as well as a get-or-create label flow. It supports international characters in subjects and message bodies and handles complex MIME structures to extract content and attachments.

Security and support

Credentials are stored locally and are accessible only to the user who configured them. Review and revoke access in Google Account settings if needed.

If you encounter issues, file a report with the appropriate support channel for the MCP server.

Available tools

send_email

Sends a new email immediately with subject, body, recipients, and optional CC/BCC.

draft_email

Creates a draft email that you can review or edit before sending.

read_email

Retrieves the content of a specific email by its message ID, including MIME-aware content extraction.

search_emails

Searches emails using Gmail search operators, returning matching messages.

modify_email

Adds or removes labels from a specific email, enabling moves across folders or archiving.

delete_email

Permanently deletes a specific email by its message ID.

list_email_labels

Lists all Gmail labels, including system and user-defined labels.

create_label

Creates a new Gmail label with visibility settings.

update_label

Renames or updates visibility settings for an existing label.

delete_label

Deletes a user-created Gmail label.

get_or_create_label

Retrieves a label by name or creates it if it does not exist.

batch_modify_emails

Modifies labels for multiple emails in batches for efficiency.

batch_delete_emails

Permanently deletes multiple emails in batches.