DOCSEARCHbyAlgolia
Submit Docs

Gmail MCP Server

repository·main·Indexed 22 days ago

https://github.com/gongrzhe/gmail-mcp-server

A Model Context Protocol (MCP) server providing AI assistants with full Gmail integration. Features include sending and reading emails, managing labels, handling attachments, creating filters, and batch modifying emails. Supports auto-authentication via Google OAuth 2.0 and can be deployed via npx, Docker, or Docker Compose.

Tokens
7.2K
Snippets
24
Records
38
Agent score
78%

What's inside @gongrzhe/server-gmail-autoauth-mcp

  1. Best Practices for Gmail Filter Management

    main

    When implementing automation via the Gmail MCP server, follow these best practices:

    1. Start Simple: Begin with basic filters using existing templates.
    2. Test Criteria: Before creating a filter, use the search_emails tool to verify that your search criteria correctly identify the intended emails.
    3. Use Labels Strategically: Build a logical label hierarchy to keep your inbox organized.
    4. Review Regularly: Periodically clean up unused or redundant filters.
    5. Combine with Batch Operations: Use filters in conjunction with batch operations to apply rules retroactively to existing emails.

  2. Install and authenticate the Gmail AutoAuth MCP server

    main

    Follow these steps to configure the local environment and authenticate with Google.

    1. Prepare the configuration directory

    Create the directory where the server stores its configuration and move your keys there:

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

    2. Run the authentication flow

    Execute the following command to launch the browser-based OAuth flow:

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

    This command will:

    • Search for gcp-oauth.keys.json in your current directory or ~/.gmail-mcp/.
    • Copy the file to ~/.gmail-mcp/ if it is found in the current directory.
    • Open your web browser for Google authentication.
    • Save your session credentials to ~/.gmail-mcp/credentials.json.
    mkdir -p ~/.gmail-mcp
mv gcp-oauth.keys.json ~/.gmail-mcp/
npx @gongrzhe/server-gmail-autoauth-mcp auth

  4. Authenticate the Gmail MCP Server

    main

    The server requires an authentication step to link your Gmail account. It looks for gcp-oauth.keys.json in either your current directory or ~/.gmail-mcp/.

    Global Authentication (Recommended)

    Move your keys to the global config folder first, then run the auth command. This allows you to authenticate once and use the server from anywhere.

    # Move keys to global config
mkdir -p ~/.gmail-mcp
mv gcp-oauth.keys.json ~/.gmail-mcp/

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

    Local Authentication

    If you run the command in a directory containing gcp-oauth.keys.json, the file will be automatically copied to ~/.gmail-mcp/.

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

    Note: Successful authentication saves credentials to ~/.gmail-mcp/credentials.json.

  5. Set up Google Cloud credentials for Gmail MCP

    main

    Before installing the server, you must create a Google Cloud Project and obtain OAuth 2.0 credentials to allow the server to access your Gmail account.

    1. Go to the Google Cloud Console.
    2. Create a new project or select an existing one.
    3. Enable the Gmail API for your project.
    4. Create OAuth 2.0 credentials:
      • Navigate to APIs & Services > Credentials.
      • Click Create Credentials > OAuth client ID.
      • Choose Desktop app or Web application.
      • If choosing Web application: Add http://localhost:3000/oauth2callback to the redirect URIs.
    5. Download the OAuth keys JSON file.
    6. Rename the downloaded file to gcp-oauth.keys.json.

  6. Common Gmail Filter Templates and Use Cases

    main

    The Gmail MCP server supports creating filters to automate email management. A common pattern is using the fromSender template to organize incoming mail based on the sender's email address.

    Newsletter Management

    Use the fromSender template to automatically organize newsletters by specifying the sender, target labels, and whether to archive the message.

    Template: fromSender Parameters:

    • senderEmail: The email address of the sender.
    • labelIds: The IDs of the labels to apply.
    • archive: Boolean indicating if the email should be archived.

    Other Use Cases

    • Work Email Organization: Filter emails from specific managers or team notification addresses.
    • Automated Filing: Automatically file financial emails or support tickets into specific label hierarchies.
    • Large Attachment Management: Apply specific labels to emails containing large attachments for easier identification.
    Template: fromSender
Parameters: senderEmail, labelIds, archive

  7. Authenticate in Cloud or Docker Environments

    main

    For environments where localhost is not accessible (e.g., n8n, cloud servers, or Docker), you must specify a custom callback URL.

    Cloud Server Authentication

    1. Configure a reverse proxy to forward traffic from your domain (e.g., https://gmail.gongrzhe.com/oauth2callback) to your server.
    2. Add the custom domain callback URL to your Google Cloud Console authorized redirect URIs.
    3. Run authentication with the custom URL:
    npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback

    Docker Support

    To run the server in Docker, mount your OAuth keys and specify the credential paths via environment variables:

    # Authentication command for Docker
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

    To use the server in Claude Desktop via Docker:

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

  9. Manual Installation and Google Cloud Setup

    main

    To install the server manually, follow these steps to obtain Google OAuth credentials:

    1. Google Cloud Project Setup:
    2. Create OAuth 2.0 Credentials:
      • Go to APIs & Services > Credentials.
      • Click Create Credentials > OAuth client ID.
      • Select Desktop app or Web application.
      • For Web applications: You MUST add http://localhost:3000/oauth2callback to the authorized redirect URIs.
      • Download the JSON key file and rename it to gcp-oauth.keys.json.
    3. Configure Claude Desktop: Add the following to your Claude Desktop configuration file:
      {
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@gongrzhe/server-gmail-autoauth-mcp"
      ]
    }
  }
}
    {
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@gongrzhe/server-gmail-autoauth-mcp"
      ]
    }
  }
}

  10. Gmail MCP Server Toolset Overview

    main

    The Gmail MCP server provides a comprehensive set of tools for interacting with a Gmail account via the Model Context Protocol. It allows for managing emails, labels, and filters.

    Core Capabilities:

    • Email Management: Send, draft, read, search, modify (labels), delete, and batch operations on emails.
    • Label Management: Create, update, delete, and retrieve Gmail labels (both system and user-defined).
    • Filter Management: Create, list, get, and delete Gmail filters, including support for pre-defined templates.
    • Attachments: Download email attachments to a specified local path.
    • Batch Operations: Perform label modifications or deletions on multiple messages efficiently using batch processing.

  12. Troubleshoot Gmail MCP installation issues

    main

    OAuth Keys

    • Verify gcp-oauth.keys.json exists in ~/.gmail-mcp/.
    • Check file permissions.
    • Ensure the keys contain valid web or installed credentials.

    Authentication Errors

    • Confirm the Gmail API is enabled in your Google Cloud Project.
    • For web applications, verify the redirect URI (http://localhost:3000/oauth2callback) is correctly configured.
    • Ensure port 3000 is available on your machine during the authentication process.

    Configuration Issues

    • Verify the ~/.gmail-mcp directory exists and has correct permissions.
    • Check that credentials.json was successfully created after running the auth command.
    • Ensure your Claude Desktop configuration JSON is properly formatted.